{"id":19611920,"url":"https://github.com/princeton-nlp/lwm","last_synced_at":"2026-03-16T09:37:51.390Z","repository":{"id":219659487,"uuid":"744721439","full_name":"princeton-nlp/lwm","owner":"princeton-nlp","description":"We develop world models that can be adapted with natural language. Intergrating these models into artificial agents allows humans to effectively control these agents through verbal communication.","archived":false,"fork":false,"pushed_at":"2024-02-10T02:53:57.000Z","size":496,"stargazers_count":22,"open_issues_count":4,"forks_count":3,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-23T18:10:05.549Z","etag":null,"topics":["language","nlp","world-models"],"latest_commit_sha":null,"homepage":"https://language-guided-world-model.github.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/princeton-nlp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-17T21:48:17.000Z","updated_at":"2025-02-24T12:17:29.000Z","dependencies_parsed_at":"2024-02-05T04:24:15.309Z","dependency_job_id":"1c4733b4-b8c8-46ca-96a0-53a58787c18b","html_url":"https://github.com/princeton-nlp/lwm","commit_stats":null,"previous_names":["princeton-nlp/lwm"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/princeton-nlp%2Flwm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/princeton-nlp%2Flwm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/princeton-nlp%2Flwm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/princeton-nlp%2Flwm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/princeton-nlp","download_url":"https://codeload.github.com/princeton-nlp/lwm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250487531,"owners_count":21438612,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["language","nlp","world-models"],"created_at":"2024-11-11T10:44:59.847Z","updated_at":"2026-03-16T09:37:51.328Z","avatar_url":"https://github.com/princeton-nlp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Language-Guided World Models: A Model-Based Approach to AI Control\nThis repository contains the code for running experiments. We propose *Language-Guided World Models* (LWMs), which can capture environment dynamics by reading language descriptions. There are two main phases of LWM learning, one being learning the language-guided world model by exploring the environment, and the other being model-based policy learning through imitation learning / behavior cloning.\n\nVisit [the project's website](https://language-guided-world-model.github.io/) to learn more.\n\n![Example of LWM](teaser.gif)\n\n## 🛠️ Getting Started: Setup\n\nCreate a conda environment\n\n```\nconda create -n lwm python=3.9 \u0026\u0026 conda activate lwm\n```\n\nInstall the relevant dependencies through pip:\n\n```\npip install -r requirements.txt\n```\n\n### 🐾 Trajectory Dataset Link\nFinally, download the trajectory dataset from [this link](https://drive.google.com/file/d/1vUwP4EzBMrmDZWhmnXFie2woWbGzjKUq/view?usp=sharing), unzip the file (~7 GB), and put the .pickle file inside `world_model/custom_dataset`\n\n### 🍀 Pre-trained Checkpoints\nRead the following sections for different steps of the training process (train WM, then train policy). We provide some checkpoints for both the trained world model, as well as the expert EMMA policy that you can use to skip world model training.\nThese were the some of the checkpoints used in the experiments described in the paper. Download the checkpoints [at this link](https://drive.google.com/file/d/1YiQyjeInXqztyffAbZ-8SDsnS2II8HUh/view?usp=sharing) and place them in an appropriate folder.\n\n## 🌎 Training the World Model\n\nFirst change directory into world_model/\n```\ncd world_model\n```\n\nIn this setting, the world model will learn from observing trajectories and the provided natural language from the game manuals. To train the world model, use the following bash script\n```\nbash scripts/train_wm.sh ${MODEL_NAME}\n```\nwhere `${MODEL_NAME}` is one of\n* `none` (observational, doesn't use language)\n* `standardv2` (standard Transformer)\n* `direct` (GPT-hard attention)\n* `emma` (our proposed EMMA-LWM model)\n* `oracle` (oracle semantic-parsing).\n\nThe above script will generate a folder in `experiments/` containing model checkpoints. For more details on the different models, see the paper. The seed is fixed here and can be changed in the script. Full results are in Table 1 of the paper.\n\nTo interact with a trained world model, run:\n```\nbash scripts/play_wm.sh ${MODEL_NAME}\n```\n\nYou can change the `game_id` in `play_wm.py` to visualize a different game. If you define a different seed for training the world model, make sure to define the same seed when playing (hard-coded in the current setup).\n\n## 🤖 Downstream Policy Learning\n\n**Note:** *For filtered behavior cloning, it requires the use of an expert policy. See paper for more details. *\n\nMake sure you are in the `world_model/` directory. First, train an expert policy and save its checkpoints (do not skip this step!):\n\n```\nbash scripts/train_emma_policy.sh\n```\n\nOnce you have learned a language-guided world model following \"[Training the World Model](#training-the-world-model)\", you can apply it to downstream policy learning on Messenger (see Table 3 for comprehensive results).\n```\nbash scripts/train_downstream.sh ${TRAIN_TASK} ${MODEL_NAME} ${SPLIT} ${GAME}\n```\nwhere\n* `${TRAIN_TASK}` is one of `imitation` (Imitation Learning) or `filtered_bc` (Filtered Behavior cloning). See paper for more details.\n* `${MODEL_NAME}` is one of the world models listed in the [Training the World Model](#training-the-world-model) section that has been trained.\n* `${SPLIT}` is the difficulty to evaluate on, and is one of `easy` (NewCombo), `medium` (NewAttr), `hard`(NewAll). See paper for more details.\n* `${GAME}` is the game id on MESSENGER to evaluate on. It ranges from 0-29.\n* `${ORACLE_CKPT}` is either `half`, which will set the oracle weights to a training checkpoint where it was roughly halfway trained. This is specifically for half-trained filtered behavior cloning (see paper for more details). In our experiments, this correponded to `policy_2000.ckpt`, but you can manually change this in the script. Otherwise, any other string will set it to the best oracle world model checkpoint on the hardest validation split.\n\nThe above script will generate a folder in `experiments/` containing model checkpoints.\n\n\n## Credits\n\n* https://github.com/eloialonso/iris\n* https://github.com/karpathy/minGPT\n\n## Citation\n\n```\n@article{zhang2024languageguided\n  title={Language-Guided World Models: A Model-Based Approach to AI Control},\n  author={Zhang, Alex and Nguyen, Khanh and Tuyls, Jens and Lin, Albert and Narasimhan, Karthik},\n  year={2024},\n  journal={arXiv},\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprinceton-nlp%2Flwm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprinceton-nlp%2Flwm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprinceton-nlp%2Flwm/lists"}