Package: hcraft
HierarchyCraft - Environements builder for hierarchical reasoning researchHierarchyCraftHierarchyCraft (hcraft for short) is a Python library designed to create arbitrary hierarchical environments that are compatible with both theOpenAI Gym Reinforcement Learning FrameworkandAIPlan4EU Unified Planning Framework. 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 asTransformations, as opposed to detailed movements and controls. But eachTransformationshas specific requirements to be valid (eg. have enought of an item, be in the right place), and these requirements may necessitate the execution of otherTransformationsfirst, inherently creating a hierarchical structure in HierarchyCraft environments.This concept is visually represented by theRequirements graphdepicting the hierarchical relationships within each HierarchyCraft environment.
TheRequirements graphis directly constructed from the list ofTransformationscomposing the environement.More details about requirements graph can be found in the documentation athcraft.requirementsand example of requirements graph for some HierarchyCraft environements can be found inhcraft.examples.No feature extraction for fast research even with low computeHierarchyCraft 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.Seehcraft.statefor more details.Create your own tailored HierarchyCraft environmentsYou can use HierarchyCraft to create various custom hierarchical environments from a list of customizedTransformations.Seehcraft.envfor a complete tutorial on creating custom environments.InstallationUsing pipWithout optional dependencies:pipinstallhcraftWith all optional dependencies:pipinstallhcraft[all]All hcraft environments can use a common graphical user interface.
With gui requirements:pipinstallhcraft[gui]Gym environment can be obtained throught the with gym requirements:pipinstallhcraft[gym]Planning problems can be obtained throught the upf interface:pipinstallhcraft[planning]QuickstartPlay yourself!Install the graphical user interface optional dependencies:pipinstallhcraft[gui]Using the command line interfaceYou can directly try to play yourself with the GUI available for any HierarchyCraft environments, for example:hcraftminecraftFor more examples:hcraft--helpUsing the programmatic interface:fromhcraftimportget_human_actionfromhcraft.examplesimportMineHcraftEnvenv=MineHcraftEnv()# or env: MineHcraftEnv = gym.make("MineHcraft-NoReward-v1")n_episodes=2for_inrange(n_episodes):env.reset()done=Falsetotal_reward=0whilenotdone:env.render()action=get_human_action(env)print(f"Human pressed:{env.world.transformations[action]}")_observation,reward,done,_info=env.step(action)total_reward+=rewardprint(f"SCORE:{total_reward}")As a Gym RL environmentUsing the programmatic interface, any HierarchyCraft environment can easily be interfaced with classic reinforcement learning agents.importnumpyasnpfromhcraft.examplesimportMineHcraftEnvdefrandom_legal_agent(observation,action_is_legal):action=np.random.choice(np.nonzero(action_is_legal)[0])returnint(action)env=MineHcraftEnv(max_step=10)done=Falseobservation=env.reset()whilenotdone:action_is_legal=env.action_masks()action=random_legal_agent(observation,action_is_legal)_observation,_reward,done,_info=env.step(action)# Other examples of HierarchyCraft environmentsfromhcraft.examplesimportTowerHcraft,RecursiveHcraft,RandomHcrafttower_env=TowerHcraft(height=3,width=2)# or tower_env = gym.make("TowerHcraft-v1", height=3, width=2)recursive_env=RecursiveHcraft(n_items=6)# or recursive_env = gym.make("RecursiveHcraft-v1", n_items=6)random_env=RandomHcraft(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)Seehcraft.envfor a more complete description.As a UPF problem for planningHierarchyCraft environments can be converted to planning problem in one line
thanks to the Unified Planning Framework (UPF):problem=env.planning_problem()print(problem.upf_problem)Then they can be solved with any compatible planner (default is enhsp):problem.solve()print(problem.plan)Seehcraft.planningfor a more complete description.More about HierarchyCraftOnline documentationLearn more in theDOCUMENTATION