# **HierarchyCraft - Environements builder for hierarchical reasoning research**
[](https://badge.fury.io/py/hcraft)
[](https://pepy.tech/project/hcraft)
[](https://pepy.tech/project/hcraft)
[](https://www.gnu.org/licenses/)
[](https://www.codacy.com/gh/IRLL/HierarchyCraft/dashboard?utm_source=github.com&utm_medium=referral&utm_content=IRLL/HierarchyCraft&utm_campaign=Badge_Grade)
[](https://www.codacy.com/gh/IRLL/HierarchyCraft/dashboard?utm_source=github.com&utm_medium=referral&utm_content=IRLL/HierarchyCraft&utm_campaign=Badge_Coverage)
[](https://github.com/psf/black)
[](https://github.com/charliermarsh/ruff)
# HierarchyCraft
HierarchyCraft (hcraft for short) is a Python library designed to create arbitrary hierarchical environments that are compatible with both the [OpenAI Gym Reinforcement Learning Framework](https://github.com/openai/gym) and [AIPlan4EU Unified Planning Framework](https://github.com/aiplan4eu/unified-planning). This library enables users to easily create complex hierarchical structures that can be used to test and develop various reinforcement learning or planning algorithms.
In environments built with HierarchyCraft the agent (player) has an inventory and can navigate into abstract zones that themselves have inventories.
The action space of HierarchyCraft environments consists of sub-tasks, referred to as _Transformations_, as opposed to detailed movements and controls. But each _Transformations_ has specific requirements to be valid (eg. have enought of an item, be in the right place), and these requirements may necessitate the execution of other _Transformations_ first, inherently creating a hierarchical structure in HierarchyCraft environments.
This concept is visually represented by the _Requirements graph_ depicting the hierarchical relationships within each HierarchyCraft environment.
The _Requirements graph_ is directly constructed from the list of _Transformations_ composing the environement.
More details about requirements graph can be found in the documentation at [`hcraft.requirements`](https://irll.github.io/HierarchyCraft/hcraft/requirements.html) and example of requirements graph for some HierarchyCraft environements can be found in [`hcraft.examples`](https://irll.github.io/HierarchyCraft/hcraft/examples.html).
## No feature extraction for fast research even with low compute
HierarchyCraft returns vectorized state information, which plainly and directly describes the player's inventory, current positions, and the inventory of the current zone. Compared to benchmarks that return grids, pixel arrays, text or sound, we directly return a low-dimensional latent representation that doesn't need to be learned.
Therefore saving compute time and allowing researchers to focus only the the hierarchical reasoning part.
See [`hcraft.state`](https://irll.github.io/HierarchyCraft/hcraft/state.html) for more details.
## Create your own tailored HierarchyCraft environments
You can use HierarchyCraft to create various custom hierarchical environments from a list of customized _Transformations_.
See [`hcraft.env`](https://irll.github.io/HierarchyCraft/hcraft/env.html) for a complete tutorial on creating custom environments.
# Installation
## Using pip
Without optional dependencies:
```bash
pip install hcraft
```
All hcraft environments can use a common graphical user interface that can be used with gui requirements:
```bash
pip install hcraft[gui]
```
Gym environment can be obtained with gym requirements:
```bash
pip install hcraft[gym]
```
Planning problems can be obtained throught the upf interface with planning requirements:
```bash
pip install hcraft[planning]
```
Some complex graph can be represented in html interactive visualisation:
```bash
pip install hcraft[htmlvis]
```
# Quickstart
## Play yourself!
Install the graphical user interface optional dependencies:
```bash
pip install hcraft[gui]
```
### Using the command line interface
You can directly try to play yourself with the GUI available for any HierarchyCraft environments, for example:
```bash
hcraft minecraft
```
For more examples:
```bash
hcraft --help
```
### Using the programmatic interface:
```python
from hcraft import get_human_action
from hcraft.examples import MineHcraftEnv
env = MineHcraftEnv()
# or env: MineHcraftEnv = gym.make("MineHcraft-NoReward-v1")
n_episodes = 2
for _ in range(n_episodes):
env.reset()
done = False
total_reward = 0
while not done:
env.render()
action = get_human_action(env)
print(f"Human pressed: {env.world.transformations[action]}")
_observation, reward, done, _info = env.step(action)
total_reward += reward
print(f"SCORE: {total_reward}")
```
## As a Gym RL environment
Using the programmatic interface, any HierarchyCraft environment can easily be interfaced with classic reinforcement learning agents.
```python
import numpy as np
from hcraft.examples import MineHcraftEnv
def random_legal_agent(observation, action_is_legal):
action = np.random.choice(np.nonzero(action_is_legal)[0])
return int(action)
env = MineHcraftEnv(max_step=10)
done = False
observation = env.reset()
while not done:
action_is_legal = env.action_masks()
action = random_legal_agent(observation, action_is_legal)
_observation, _reward, done, _info = env.step(action)
```
```python
# Other examples of HierarchyCraft environments
from hcraft.examples import TowerHcraftEnv, RecursiveHcraftEnv, RandomHcraftEnv
tower_env = TowerHcraftEnv(height=3, width=2)
# or tower_env = gym.make("TowerHcraft-v1", height=3, width=2)
recursive_env = RecursiveHcraftEnv(n_items=6)
# or recursive_env = gym.make("RecursiveHcraft-v1", n_items=6)
random_env = RandomHcraftEnv(n_items_per_n_inputs={0:2, 1:5, 2:10}, seed=42)
# or random_env = gym.make("RandomHcraft-v1", n_items_per_n_inputs={0:2, 1:5, 2:10}, seed=42)
```
<!-- Run MineHcraft with MaskablePPO from sb3 agent [code] -->
See [`hcraft.env`](https://irll.github.io/HierarchyCraft/hcraft/env.html) for a more complete description.
## As a UPF problem for planning
HierarchyCraft environments can be converted to planning problem in one line
thanks to the Unified Planning Framework (UPF):
```python
problem = env.planning_problem()
print(problem.upf_problem)
```
Then they can be solved with any compatible planner (default is enhsp):
```python
problem.solve()
print(problem.plan)
```
See [`hcraft.planning`](https://irll.github.io/HierarchyCraft/hcraft/planning.html) for a more complete description.
# More about HierarchyCraft
## Online documentation
Learn more in the [DOCUMENTATION](https://irll.github.io/HierarchyCraft/hcraft.html)
## Contributing
You want to contribute to HierarchyCraft ? See our [contributions guidelines](CONTRIBUTING.md) and join us !
Raw data
{
"_id": null,
"home_page": null,
"name": "hcraft",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "gym, hcraft, minecraft, hierachical, reinforcement, learning",
"author": "Math\u00efs F\u00e9d\u00e9rico",
"author_email": "Math\u00efs F\u00e9d\u00e9rico <mathfederico@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ac/70/0e7f1debbf5c08f58d572b01b3ef8b5e6da14de9c1554f46044e5dab76de/hcraft-1.2.5.tar.gz",
"platform": null,
"description": "# **HierarchyCraft - Environements builder for hierarchical reasoning research**\n\n[](https://badge.fury.io/py/hcraft)\n[](https://pepy.tech/project/hcraft)\n[](https://pepy.tech/project/hcraft)\n[](https://www.gnu.org/licenses/)\n\n[](https://www.codacy.com/gh/IRLL/HierarchyCraft/dashboard?utm_source=github.com&utm_medium=referral&utm_content=IRLL/HierarchyCraft&utm_campaign=Badge_Grade)\n[](https://www.codacy.com/gh/IRLL/HierarchyCraft/dashboard?utm_source=github.com&utm_medium=referral&utm_content=IRLL/HierarchyCraft&utm_campaign=Badge_Coverage)\n[](https://github.com/psf/black)\n[](https://github.com/charliermarsh/ruff)\n\n\n# HierarchyCraft\n\nHierarchyCraft (hcraft for short) is a Python library designed to create arbitrary hierarchical environments that are compatible with both the [OpenAI Gym Reinforcement Learning Framework](https://github.com/openai/gym) and [AIPlan4EU Unified Planning Framework](https://github.com/aiplan4eu/unified-planning). This library enables users to easily create complex hierarchical structures that can be used to test and develop various reinforcement learning or planning algorithms.\n\nIn environments built with HierarchyCraft the agent (player) has an inventory and can navigate into abstract zones that themselves have inventories.\n\nThe action space of HierarchyCraft environments consists of sub-tasks, referred to as _Transformations_, as opposed to detailed movements and controls. But each _Transformations_ has specific requirements to be valid (eg. have enought of an item, be in the right place), and these requirements may necessitate the execution of other _Transformations_ first, inherently creating a hierarchical structure in HierarchyCraft environments.\n\nThis concept is visually represented by the _Requirements graph_ depicting the hierarchical relationships within each HierarchyCraft environment.\nThe _Requirements graph_ is directly constructed from the list of _Transformations_ composing the environement.\n\n\n\nMore details about requirements graph can be found in the documentation at [`hcraft.requirements`](https://irll.github.io/HierarchyCraft/hcraft/requirements.html) and example of requirements graph for some HierarchyCraft environements can be found in [`hcraft.examples`](https://irll.github.io/HierarchyCraft/hcraft/examples.html).\n\n## No feature extraction for fast research even with low compute\n\nHierarchyCraft returns vectorized state information, which plainly and directly describes the player's inventory, current positions, and the inventory of the current zone. Compared to benchmarks that return grids, pixel arrays, text or sound, we directly return a low-dimensional latent representation that doesn't need to be learned.\nTherefore saving compute time and allowing researchers to focus only the the hierarchical reasoning part.\n\n\n\nSee [`hcraft.state`](https://irll.github.io/HierarchyCraft/hcraft/state.html) for more details.\n\n## Create your own tailored HierarchyCraft environments\n\nYou can use HierarchyCraft to create various custom hierarchical environments from a list of customized _Transformations_.\n\nSee [`hcraft.env`](https://irll.github.io/HierarchyCraft/hcraft/env.html) for a complete tutorial on creating custom environments.\n\n\n# Installation\n\n## Using pip\n\nWithout optional dependencies:\n\n```bash\npip install hcraft\n```\n\nAll hcraft environments can use a common graphical user interface that can be used with gui requirements:\n\n```bash\npip install hcraft[gui]\n```\n\nGym environment can be obtained with gym requirements:\n\n```bash\npip install hcraft[gym]\n```\n\nPlanning problems can be obtained throught the upf interface with planning requirements:\n\n```bash\npip install hcraft[planning]\n```\n\nSome complex graph can be represented in html interactive visualisation:\n\n```bash\npip install hcraft[htmlvis]\n```\n\n# Quickstart\n\n## Play yourself!\n\n\n\nInstall the graphical user interface optional dependencies:\n```bash\npip install hcraft[gui]\n```\n\n### Using the command line interface\n\nYou can directly try to play yourself with the GUI available for any HierarchyCraft environments, for example:\n```bash\nhcraft minecraft\n```\n\nFor more examples:\n```bash\nhcraft --help\n```\n### Using the programmatic interface:\n\n```python\nfrom hcraft import get_human_action\nfrom hcraft.examples import MineHcraftEnv\n\nenv = MineHcraftEnv()\n# or env: MineHcraftEnv = gym.make(\"MineHcraft-NoReward-v1\")\nn_episodes = 2\nfor _ in range(n_episodes):\n env.reset()\n done = False\n total_reward = 0\n while not done:\n env.render()\n action = get_human_action(env)\n print(f\"Human pressed: {env.world.transformations[action]}\")\n\n _observation, reward, done, _info = env.step(action)\n total_reward += reward\n\n print(f\"SCORE: {total_reward}\")\n```\n\n## As a Gym RL environment\n\nUsing the programmatic interface, any HierarchyCraft environment can easily be interfaced with classic reinforcement learning agents.\n\n```python\nimport numpy as np\nfrom hcraft.examples import MineHcraftEnv\n\ndef random_legal_agent(observation, action_is_legal):\n action = np.random.choice(np.nonzero(action_is_legal)[0])\n return int(action)\n\nenv = MineHcraftEnv(max_step=10)\ndone = False\nobservation = env.reset()\nwhile not done:\n action_is_legal = env.action_masks()\n action = random_legal_agent(observation, action_is_legal)\n _observation, _reward, done, _info = env.step(action)\n```\n\n\n```python\n# Other examples of HierarchyCraft environments\nfrom hcraft.examples import TowerHcraftEnv, RecursiveHcraftEnv, RandomHcraftEnv\n\ntower_env = TowerHcraftEnv(height=3, width=2)\n# or tower_env = gym.make(\"TowerHcraft-v1\", height=3, width=2)\nrecursive_env = RecursiveHcraftEnv(n_items=6)\n# or recursive_env = gym.make(\"RecursiveHcraft-v1\", n_items=6)\nrandom_env = RandomHcraftEnv(n_items_per_n_inputs={0:2, 1:5, 2:10}, seed=42)\n# or random_env = gym.make(\"RandomHcraft-v1\", n_items_per_n_inputs={0:2, 1:5, 2:10}, seed=42)\n```\n<!-- Run MineHcraft with MaskablePPO from sb3 agent [code] -->\n\nSee [`hcraft.env`](https://irll.github.io/HierarchyCraft/hcraft/env.html) for a more complete description.\n\n## As a UPF problem for planning\n\nHierarchyCraft environments can be converted to planning problem in one line\nthanks to the Unified Planning Framework (UPF):\n\n```python\nproblem = env.planning_problem()\nprint(problem.upf_problem)\n```\n\nThen they can be solved with any compatible planner (default is enhsp):\n\n```python\nproblem.solve()\nprint(problem.plan)\n```\n\nSee [`hcraft.planning`](https://irll.github.io/HierarchyCraft/hcraft/planning.html) for a more complete description.\n\n\n# More about HierarchyCraft\n\n## Online documentation\n\nLearn more in the [DOCUMENTATION](https://irll.github.io/HierarchyCraft/hcraft.html)\n\n## Contributing\n\nYou want to contribute to HierarchyCraft ? See our [contributions guidelines](CONTRIBUTING.md) and join us !\n\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "Lightweight environments to study hierarchical reasoning",
"version": "1.2.5",
"project_urls": {
"Source": "https://github.com/IRLL/HierarchyCraft"
},
"split_keywords": [
"gym",
" hcraft",
" minecraft",
" hierachical",
" reinforcement",
" learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c255d6d2a3fd295697d107f703c88bbe7f12a237fb51513bcee0f443ab0811e7",
"md5": "34dda270f007da17a50b1fd2cdc5339f",
"sha256": "d91c4365b518bfe0cbdfa8c837fdcde3c1cb726905f00cc2ca6950cfceca47fb"
},
"downloads": -1,
"filename": "hcraft-1.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34dda270f007da17a50b1fd2cdc5339f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 3856299,
"upload_time": "2024-08-09T12:20:32",
"upload_time_iso_8601": "2024-08-09T12:20:32.844684Z",
"url": "https://files.pythonhosted.org/packages/c2/55/d6d2a3fd295697d107f703c88bbe7f12a237fb51513bcee0f443ab0811e7/hcraft-1.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ac700e7f1debbf5c08f58d572b01b3ef8b5e6da14de9c1554f46044e5dab76de",
"md5": "7f0bf345f30eba30797576909151a290",
"sha256": "85edf8fa5c22f721e8fa983f0714913b7ded9b949ab3d9d962e1039e834cd2d4"
},
"downloads": -1,
"filename": "hcraft-1.2.5.tar.gz",
"has_sig": false,
"md5_digest": "7f0bf345f30eba30797576909151a290",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 12805182,
"upload_time": "2024-08-09T12:20:35",
"upload_time_iso_8601": "2024-08-09T12:20:35.297685Z",
"url": "https://files.pythonhosted.org/packages/ac/70/0e7f1debbf5c08f58d572b01b3ef8b5e6da14de9c1554f46044e5dab76de/hcraft-1.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-09 12:20:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IRLL",
"github_project": "HierarchyCraft",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "networkx",
"specs": [
[
">=",
"2.5.1"
]
]
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "seaborn",
"specs": []
},
{
"name": "hebg",
"specs": [
[
">=",
"0.2.3"
]
]
}
],
"lcname": "hcraft"
}
JSON
