irll-crafting 1.0.2

Lightweight environments to study hierarchical reasoning

Crafting - An environement builder for hierarchical ML research

But what is Crafting ?

Crafting is NOT an environment, it's an environment builder.

Crafting allows to generate arbitrarely hierarchical environments for machine learning research purposes.

It uses the classic reinforcement learning framework, player is in a state and can take actions to update the state.

A Crafting environment is a sandbox environment composed of items, zones, and transformations.

The main example of Crafting environment is the MineCrafting environment that mimics the (complex) hierarchies of the popular game Minecraft.

You can use Crafting to create your own customized environments. For more examples, see examples.

Installation

Using pip.

Without optional dependencies:

pip install irll-crafting

With all optional dependencies:

pip install irll-crafting[all]

All crafting environments can use a common graphical user interface. With gui requirements:

pip install irll-crafting[gui]

Environment can also be obtained throught the gym interface: With gym requirements:

pip install irll-crafting[gym]

Build from source (for contributions)

git clone https://github.com/IRLL/Crafting.git

Install crafting as an editable package

pip install -e .[all]

Install dev requirements

pip install -r requirements-dev.txt

Check installation by running tests

pytest

Quickstart

Play MineCrafting yourself! (need gui dependencies)

Using the command line interface:

crafting minecraft

See more options with:

crafting --help

Using the programmatic interface:

from crafting import MineCraftingEnv, get_human_action

env = MineCraftingEnv()
# or env: MineCraftingEnv = gym.make("MineCrafting-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}")

Run MineCrafting with autonomous agents

Using the programmatic interface, any Crafting environment can easily be interfaced with any agent.

import numpy as np
from crafting import MineCraftingEnv

def random_legal_agent(observation, action_is_legal):
    action = np.random.choice(np.nonzero(action_is_legal)[0])
    return action

env = MineCraftingEnv(max_step=10)
done = False
observation = env.reset()
while not done:
    action_is_legal = env.actions_mask
    action = random_legal_agent(observation, action_is_legal)
    _observation, _reward, done, _info = env.step(action)

Other crafting environments

See crafting.examples.

from crafting import TowerCrafting, RecursiveCrafting, RandomCrafting

tower_env = TowerCrafting(height=3, width=2)
# or tower_env = gym.make("TowerCrafting-v1", height=3, width=2)
recursive_env = RecursiveCrafting(n_items=6)
# or recursive_env = gym.make("RecursiveCrafting-v1", n_items=6)
random_env = RandomCrafting(n_items_per_n_inputs={0:2, 1:5, 2:10}, seed=42)
# or random_env = gym.make("RandomCrafting-v1", n_items_per_n_inputs={0:2, 1:5, 2:10}, seed=42)

More about Crafting

Add a Purpose to the player

See crafting.purpose.

Get a solving behavior for any given task

See crafting.solving_behaviors.

Details of the environment state

See crafting.state.

Plot the underlying requirements graph

See crafting.requirements.

Create your own customized Crafting environment

See crafting.env.

Find everything in the documentation: