| Name | homegrid JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | |
| Summary | A minimal home gridworld environment to test how agents use language hints. |
| upload_time | 2023-08-16 20:35:51 |
| maintainer | |
| docs_url | None |
| author | Jessy Lin |
| requires_python | >=3.8,<4.0 |
| license | |
| keywords |
environment
agent
rl
language
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center" font-weight="bold">
A minimal home grid world environment to evaluate language understanding in interactive agents.
</p>
# 🏠 Getting Started
Play as a human:
```bash
$ pip install -e .
$ ./homegrid/manual_control.py
```
Use as a gym environment:
```python
import gym
import homegrid
env = gym.make("homegrid-task")
```
See `homegrid/__init__.py` for the environment configurations used in the paper [Learning to Model the World with Language](https://dynalang.github.io/).
# 📑 Documentation
HomeGrid tests whether agents can learn to use language that provides information about the world. In addition to task instructions, the env provides scripted _language hints_, simulating knowledge that agents might learn from humans (e.g., in a collaborative setting) or read in text (e.g., on Wikipedia). Agents navigate around a house to find objects and interact with them to perform tasks, while learning how to understand language from experience.
### ⚡️ Quick Info
- pixel observations (3x3 partial view of the house)
- discrete action space (movement + object interaction)
- 3 rooms, 7 objects (3 trash bins, 4 trash objects)
- multitask with language instructions + hints
- randomized object placement and object dynamics
**Task Templates (38 total tasks):**
- find the `object/bin`: the agent will receive a reward of 1 if it is facing the correct object / bin
- get the `object`: the agent will receive a reward of 1 if it has the correct object in inventory
- put the `object` in the `bin`: the agent will receive a reward of 1 if the bin contains the object
- move the `object` to the `room`: the agent will receive a reward of 1 if the object is in the room
- open the `bin`: the agent will receive a reward of 1 if the bin is in the open state
**Language Types and Templates**
- **Future Observations**: descriptions of what agents might observe in the future, such as "The plates are in the kitchen."
- _"`object/bin` is in the `room`"_: the object or bin is in the indicated room
- _"i moved the `object` to the `room`"_: the object has been moved to the room
- _"there will be `object` in the `room`"_: the object will spawn in the room in five timesteps
- **Dynamics**: descriptions of environment dynamics, such as "Pedal to open the compost bin."
- _"`action` to open the `bin`"_: the indicated action is the correct action to open the bin
- **Corrections**: interactive, task-specific feedback based on what the agent is currently doing, such as "Turn around."
- _"no, turn around"_: the agent's distance to the current goal object or bin (given the task) has increased compared to the last timestep
Environment instances are provided for task instruction + each of the types above in `homegrid/__init__.py`.
Language is streamed one token per timestep by default. Some strings are higher priority than others and may interrupt a string that is currently being read. See `homegrid/language_wrappers.py`.
# 💻 Development
New development and extensions to the environment are welcome!
### Adding new language utterances
Sentences are pre-embedded and cached into a file for training efficiency. You'll have to append the additional sentences to `homegrid/homegrid_sentences.txt` and re-generate the cached token and embedding file with the following command:
```bash
python scripts/embed_offline.py \
--infile homegrid/homegrid_sentences.txt \
--outfile homegrid/homecook_embeds.pkl \
--model t5
```
### Adding new layouts and objects
HomeGrid currently has one layout and a fixed set of objects that are sampled to populate each episode. Many of the receptacles and containers (e.g. cabinets) are disabled for simplicity.
To add new layouts, create a new class in `homegrid/layout.py`.
To add new static (non-interactive) objects, add assets to `homegrid/assets.py` and then specify where they are rendered in the `homegrid/layout.py`.
To add new interactive objects, additionally specify how they behave in `homegrid/homegrid_base.py:step`.
# Acknowledgments
HomeGrid is based on [MiniGrid](https://github.com/Farama-Foundation/Minigrid).
The environment assets are thanks to [limezu](https://limezu.itch.io/) and [Mounir Tohami](https://mounirtohami.itch.io/).
# Citation
```
@article{lin2023learning,
title={Learning to Model the World with Language},
author={Jessy Lin and Yuqing Du and Olivia Watkins and Danijar Hafner and Pieter Abbeel and Dan Klein and Anca Dragan},
year={2023},
eprint={2308.01399},
archivePrefix={arXiv},
}
```
Raw data
{
"_id": null,
"home_page": "",
"name": "homegrid",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "environment,agent,rl,language",
"author": "Jessy Lin",
"author_email": "jessy81697@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/4e/2a/9dedbcf630a90a1fd32d8e771e42eb2aff70c8c6a2204115e069e7d3aaab/homegrid-0.1.1.tar.gz",
"platform": null,
"description": "\n\n<p align=\"center\" font-weight=\"bold\">\nA minimal home grid world environment to evaluate language understanding in interactive agents.\n</p>\n\n# \ud83c\udfe0 Getting Started\n\nPlay as a human:\n```bash\n$ pip install -e .\n$ ./homegrid/manual_control.py\n```\n\nUse as a gym environment:\n```python\nimport gym\nimport homegrid\nenv = gym.make(\"homegrid-task\")\n```\nSee `homegrid/__init__.py` for the environment configurations used in the paper [Learning to Model the World with Language](https://dynalang.github.io/).\n\n# \ud83d\udcd1 Documentation\n\nHomeGrid tests whether agents can learn to use language that provides information about the world. In addition to task instructions, the env provides scripted _language hints_, simulating knowledge that agents might learn from humans (e.g., in a collaborative setting) or read in text (e.g., on Wikipedia). Agents navigate around a house to find objects and interact with them to perform tasks, while learning how to understand language from experience.\n\n### \u26a1\ufe0f Quick Info\n- pixel observations (3x3 partial view of the house)\n- discrete action space (movement + object interaction)\n- 3 rooms, 7 objects (3 trash bins, 4 trash objects)\n- multitask with language instructions + hints\n- randomized object placement and object dynamics\n\n**Task Templates (38 total tasks):**\n- find the `object/bin`: the agent will receive a reward of 1 if it is facing the correct object / bin\n- get the `object`: the agent will receive a reward of 1 if it has the correct object in inventory\n- put the `object` in the `bin`: the agent will receive a reward of 1 if the bin contains the object\n- move the `object` to the `room`: the agent will receive a reward of 1 if the object is in the room\n- open the `bin`: the agent will receive a reward of 1 if the bin is in the open state\n\n**Language Types and Templates**\n\n- **Future Observations**: descriptions of what agents might observe in the future, such as \"The plates are in the kitchen.\"\n - _\"`object/bin` is in the `room`\"_: the object or bin is in the indicated room\n - _\"i moved the `object` to the `room`\"_: the object has been moved to the room\n - _\"there will be `object` in the `room`\"_: the object will spawn in the room in five timesteps\n- **Dynamics**: descriptions of environment dynamics, such as \"Pedal to open the compost bin.\"\n - _\"`action` to open the `bin`\"_: the indicated action is the correct action to open the bin\n- **Corrections**: interactive, task-specific feedback based on what the agent is currently doing, such as \"Turn around.\"\n - _\"no, turn around\"_: the agent's distance to the current goal object or bin (given the task) has increased compared to the last timestep\n\nEnvironment instances are provided for task instruction + each of the types above in `homegrid/__init__.py`.\n\nLanguage is streamed one token per timestep by default. Some strings are higher priority than others and may interrupt a string that is currently being read. See `homegrid/language_wrappers.py`.\n\n# \ud83d\udcbb Development\n\nNew development and extensions to the environment are welcome!\n\n### Adding new language utterances\n\nSentences are pre-embedded and cached into a file for training efficiency. You'll have to append the additional sentences to `homegrid/homegrid_sentences.txt` and re-generate the cached token and embedding file with the following command:\n```bash\npython scripts/embed_offline.py \\\n --infile homegrid/homegrid_sentences.txt \\\n --outfile homegrid/homecook_embeds.pkl \\\n --model t5\n```\n\n### Adding new layouts and objects\n\nHomeGrid currently has one layout and a fixed set of objects that are sampled to populate each episode. Many of the receptacles and containers (e.g. cabinets) are disabled for simplicity.\n\nTo add new layouts, create a new class in `homegrid/layout.py`.\n\nTo add new static (non-interactive) objects, add assets to `homegrid/assets.py` and then specify where they are rendered in the `homegrid/layout.py`.\n\nTo add new interactive objects, additionally specify how they behave in `homegrid/homegrid_base.py:step`.\n\n# Acknowledgments\n\nHomeGrid is based on [MiniGrid](https://github.com/Farama-Foundation/Minigrid).\nThe environment assets are thanks to [limezu](https://limezu.itch.io/) and [Mounir Tohami](https://mounirtohami.itch.io/).\n\n# Citation\n\n```\n@article{lin2023learning,\n title={Learning to Model the World with Language},\n author={Jessy Lin and Yuqing Du and Olivia Watkins and Danijar Hafner and Pieter Abbeel and Dan Klein and Anca Dragan},\n year={2023},\n eprint={2308.01399},\n archivePrefix={arXiv},\n}\n```\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A minimal home gridworld environment to test how agents use language hints.",
"version": "0.1.1",
"project_urls": null,
"split_keywords": [
"environment",
"agent",
"rl",
"language"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f5a3ea5843d80f5d117aded1f1b4ddfa6ee0fbefaa1ffabd60c4b71beb71e2c4",
"md5": "5b68ea367892c3268fdb7f17b1582ff9",
"sha256": "5a8011038388dced3a8452ab131b051cdf153b258ddfe939edc48f3483d213ea"
},
"downloads": -1,
"filename": "homegrid-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b68ea367892c3268fdb7f17b1582ff9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 1290477,
"upload_time": "2023-08-16T20:35:49",
"upload_time_iso_8601": "2023-08-16T20:35:49.578657Z",
"url": "https://files.pythonhosted.org/packages/f5/a3/ea5843d80f5d117aded1f1b4ddfa6ee0fbefaa1ffabd60c4b71beb71e2c4/homegrid-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4e2a9dedbcf630a90a1fd32d8e771e42eb2aff70c8c6a2204115e069e7d3aaab",
"md5": "32ced49902f8fc6dcbb529376d913b46",
"sha256": "41890971dc8868626bbdb26a78ee50679d9d30e744c8f474b095b42c84d3fdab"
},
"downloads": -1,
"filename": "homegrid-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "32ced49902f8fc6dcbb529376d913b46",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 1271631,
"upload_time": "2023-08-16T20:35:51",
"upload_time_iso_8601": "2023-08-16T20:35:51.539552Z",
"url": "https://files.pythonhosted.org/packages/4e/2a/9dedbcf630a90a1fd32d8e771e42eb2aff70c8c6a2204115e069e7d3aaab/homegrid-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-16 20:35:51",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "homegrid"
}
