textworld.generator

exception textworld.generator.GenerationWarning[source]

Bases: UserWarning

textworld.generator.compile_game(game, options=None)[source]

Compile a game.

Parameters
Returns

The path to compiled game.

textworld.generator.make_game(options)[source]

Make a game (map + objects + quest).

Parameters

options (GameOptions) – For customizing the game generation (see textworld.GameOptions for the list of available options).

Return type

Game

Returns

Generated game.

textworld.generator.make_game_with(world, quests=None, grammar=None)[source]
textworld.generator.make_grammar(options={}, rng=None)[source]
Return type

Grammar

textworld.generator.make_map(n_rooms, size=None, rng=None, possible_door_states=['open', 'closed', 'locked'])[source]

Make a map.

Parameters

  • n_rooms (int) – Number of rooms in the map.

  • size (tuple of int) – Size (height, width) of the grid delimiting the map.

textworld.generator.make_quest(world, options=None)[source]
textworld.generator.make_small_map(n_rooms, rng=None, possible_door_states=['open', 'closed', 'locked'])[source]

Make a small map.

The map will contains one room that connects to all others.

Parameters

  • n_rooms (int) – Number of rooms in the map (maximum of 5 rooms).

  • possible_door_states (list of str, optional) – Possible states doors can have.

textworld.generator.make_world(world_size, nb_objects=0, rngs=None)[source]

Make a world (map + objects).

Parameters

  • world_size (int) – Number of rooms in the world.

  • nb_objects (int) – Number of objects in the world.

textworld.generator.make_world_with(rooms, rng=None)[source]

Make a world that contains the given rooms.

Parameters

rooms (list of textworld.logic.Variable) – Rooms in the map. Variables must have type ‘r’.

exception textworld.generator.chaining.QuestGenerationError[source]

Bases: Exception

class textworld.generator.chaining.Chain(initial_state, nodes)[source]

Bases: object

An initial state and a chain of actions forming a quest.

nodes

The dependency tree of this quest.

initial_state

The initial state from which the actions start.

actions

The sequence of actions forming this quest.

class textworld.generator.chaining.ChainNode(action, depth, breadth, parent)[source]

Bases: object

A node in a chain of actions.

action

The action to perform at this step.

depth

This node’s depth in the dependency tree.

breadth

This node’s breadth in the dependency tree.

parent

This node’s parent in the dependency tree.

class textworld.generator.chaining.ChainingOptions[source]

Bases: object

Options for customizing the behaviour of chaining.

backward

Whether to run chaining forwards or backwards. Forward chaining produces a sequence of actions that start at the provided state, while backward chaining produces a sequence of actions that end up at the provided state.

min_length

The minimum length of the generated quests.

max_length

The maximum length of the generated quests.

min_depth

The minimum depth (length) of the generated independent subquests.

max_depth

The maximum depth (length) of the generated independent subquests.

min_breadth

The minimum breadth of the generated quests. When this is higher than 1, the generated quests will have multiple parallel subquests. In this case, min_depth and max_depth limit the length of these independent subquests, not the total size of the quest.

max_breadth

The maximum breadth of the generated quests.

subquests

Whether to also return incomplete quests, which could be extended without reaching the depth or breadth limits.

independent_chains

Whether to allow totally independent parallel chains.

create_variables

Whether new variables may be created during chaining.

fixed_mapping

A fixed mapping from placeholders to variables, for singletons.

rng

If provided, randomize the order of the quests using this random number generator.

logic

The rules of the game.

rules_per_depth

A list of lists of rules for restricting the allowed actions at certain depths.

restricted_types

A set of types that may not have new variables created.

allowed_types

A set of types that are allowed to have new variables created.

check_action(state, action)[source]

Check if an action should be allowed in this state.

The default implementation disallows actions that would create new facts that don’t mention any new variables.

Parameters

  • state (State) – The current state.

  • action (Action) – The action being applied.

Return type

bool

Returns

Whether that action should be allowed.

check_new_variable(state, type, count)[source]

Check if a new variable should be allowed to be created in this state.

Parameters

  • state (State) – The current state.

  • type (str) – The type of variable being created.

  • count (int) – The total number of variables of that type.

Return type

bool

Returns

Whether that variable should be allowed to be created.

copy()[source]
Return type

ChainingOptions

get_rules(depth)[source]

Get the relevant rules for this depth.

Parameters

depth (int) – The current depth in the chain.

Return type

Iterable[Rule]

Returns

The rules that may be applied at this depth in the chain.

property fixed_mapping
Return type

GameLogic

property logic
Return type

GameLogic

textworld.generator.chaining.get_chains(state, options)[source]

Generates chains of actions (quests) starting from or ending at the given state.

Parameters

  • state (State) – The initial state for chaining.

  • options (ChainingOptions) – Options to configure chaining behaviour.

Return type

Iterable[Chain]

Returns

All possible quests according to the constraints.

textworld.generator.chaining.sample_quest(state, options)[source]

Samples a single chain of actions (a quest) starting from or ending at the given state.

Parameters

  • state (State) – The initial state for chaining.

  • options (ChainingOptions) – Options to configure chaining behaviour. Set options.rng to sample a random quest.

Return type

Optional[Chain]

Returns

A single possible quest.

Raises

QuestGenerationError – No quest could be generated given the provided chaining options.

class textworld.generator.dependency_tree.DependencyTree(element_type=<class 'textworld.generator.dependency_tree.DependencyTreeElement'>, trees=[])[source]

Bases: object

copy()[source]
Return type

DependencyTree

push(value, allow_multi_root=False)[source]

Add a value to this dependency tree.

Adding a value already present in the tree does not modify the tree.

Parameters

  • value (Any) – value to add.

  • allow_multi_root (bool) – if True, allow the value to spawn an additional root if needed.

Return type

bool

remove(value)[source]

Remove all leaves having the given value.

The value to remove needs to belong to at least one leaf in this tree. Otherwise, the tree remains unchanged.

Parameters

value (Any) – value to remove from the tree.

Return type

bool

Returns

Whether the tree has changed or not.

property empty
Return type

bool

property leaves_elements
Return type

List[DependencyTreeElement]

property leaves_values
Return type

List[Any]

property values
Return type

List[Any]

class textworld.generator.dependency_tree.DependencyTreeElement(value)[source]

Bases: object

Representation of an element in the dependency tree.

The notion of dependency and ordering should be defined for these elements.

Subclasses should override depends_on, __lt__ and __str__ accordingly.

depends_on(other)[source]

Check whether this element depends on the other.

Return type

bool

is_distinct_from(others)[source]

Check whether this element is distinct from others.

Return type

bool

class textworld.generator.logger.GameLogger(group_actions=True)[source]

Bases: object

aggregate(other)[source]
collect(game)[source]
display_stats()[source]
static load(filename)[source]
save(filename)[source]
stats()[source]
exception textworld.generator.vtypes.NotEnoughNounsError[source]

Bases: NameError

class textworld.generator.vtypes.VariableType(type, name, parent=None)[source]

Bases: object

classmethod deserialize(data)[source]
Return type

VariableType

classmethod parse(expr)[source]

Parse a variable type expression.

Parameters

expr (str) – The string to parse, in the form name: type -> parent1 & parent2 or name: type for root node.

Return type

VariableType

serialize()[source]
Return type

str

class textworld.generator.vtypes.VariableTypeTree(vtypes)[source]

Bases: object

Manages hierarchy of types defined in ./grammars/variables.txt. Used for extending the rules.

count(state)[source]

Counts how many objects there are of each type.

descendants(vtype)[source]

Given a variable type, return all possible descendants.

classmethod deserialize(data)[source]
Return type

VariableTypeTree

get_ancestors(vtype)[source]

List all ancestors of a type where the closest ancetors are first.

get_description(vtype)[source]
is_constant(vtype)[source]
is_descendant_of(child, parents)[source]

Return if child is a descendant of parent

classmethod load(path)[source]

Read variables from text file.

sample(parent_type, rng, exceptions=[], include_parent=True, probs=None)[source]

Sample an object type given the parent’s type.

serialize()[source]
Return type

List

CHEST = 'c'
CLASS_HOLDER = ['c', 's']
SUPPORTER = 's'
textworld.generator.vtypes.get_new(type, types_counts, max_types_counts=None)[source]

Get the next available id for a given type.

textworld.generator.vtypes.parse_variable_types(content)[source]

Parse a list VariableType expressions.