pydialogue.environment package

Submodules

pydialogue.environment.actions module

This module lists all functions the environment uses to provide feedback to the player.

pydialogue.environment.actions.drop(entity, player, location, location_position)

Returns the environment response after the player tries dropping the entity at the location.

Parameters:

• entity (Entity) – The entity that the player tries dropping.

• player (Entity) – The player that tries dropping the entity.

• location (Entity) – It represents the location where the entity should be dropped.

• location_position (str) – The preposition refers to the target location. For example: in, on, under.

Returns:

The list of valid responses. If the entity can not be dropped, a negative response is returned.

Return type:

list

pydialogue.environment.actions.get(entity, player, location, location_position)

Returns the environment response after the player tries getting the entity at the location.

Parameters:

• entity (Entity) – The entity that the player tries taking.

• player (Entity) – The player that tries taking the entity.

• location (Entity) – The location where the entity is found.

• location_position (str) – The location position where the entity is found. For example: on, in, under

Returns:

The list of valid responses. If the entity is not gettable, a negative response is returned.

Return type:

list

pydialogue.environment.actions.go(player, direction, from_location=None)

Returns the environment response when a player tries moving in a direction from a certain location.

Parameters:

• player (Entity) – The player that tries moving.

• direction (str) – The direction of movement. This can be north, east, northeast, … and so on. If the string is not a direction or the direction is not present in player.properties[‘location’] a negative response is returned.

• from_location (Entity) – The location where the player is. If the from_location is not the correct one, a negative feedback is provided.

Returns:

log – A list of valid responses.

Return type:

list

pydialogue.environment.actions.look(entity, player, position, location)

Returns the environment response after the player looks (in/on/under) the entity at the specified location.

Please refer to look_object_response for more information.

Parameters:

• entity (Entity) – The entity that the player looks in/on/under.

• player (Entity) – The player looking in/on/under the entity.

• position (str) – The location preposition (‘in’, ‘on’, ‘under’).

• location (list) – The location is a list of two values: a location preposition (string) and a location (Entity). The location refers to where the entity is located.

Returns:

log – A list of valid responses

Return type:

list

pydialogue.environment.actions.look_container(entity, location_preposition, can_not_look_res)

Returns the environment response after a player looks in the container entity.

Parameters:

• entity (Entity) – The entity that the player looks in. The entity has to be a supporter (have attribute ‘container’).

• location_preposition (str) – The preposition has to be ‘in’ in order to return a non-empty response.

• can_not_look_res (Sentence) – The sentence “<player> can not look in <entity>” is used if looking in the container is not possible. For example, this can happen if the container is not opened or the container is locked.

Returns:

A list comprising a single sentence outputting what items the entity has in it or outputting that the entity contains no items.

Return type:

list

pydialogue.environment.actions.look_hollow(entity, location_preposition)

Returns the environment response after a player looks under a hollow entity.

Parameters:

• entity (Entity) – The entity should have an attribute hollow.

• location_preposition (str) – The location position should be ‘under’, otherwise empty list is returned.

Returns:

A comprising a single sentence outputting what items the entity has under it or outputting that the entity has no items under.

Return type:

list

pydialogue.environment.actions.look_inventory(entity, location_preposition)

Returns the environment response after a player looks in another player’s inventory or in its own inventory.

Parameters:

• entity (Entity) – The entity should have an attribute player.

• location_preposition (str) – The location position should be ‘in’, and it refers to looks in <entity>.

Returns:

response – A list of single sentence outputting what items the player contains or outputting that the player has no items. If the location position is not ‘in’, an empty response is returned.

Return type:

list

pydialogue.environment.actions.look_object_response(entity, player, location_position, can_not_look_res)

Finds the suitable response when the player looks in/on/under the entity depending on the entity’s properties and attributes. For example, if the entity is a table (which is a supporter) and the location preposition is ‘on’, then the look_supporter function is called, and the items that are on top of the table are given as part of the environmental response.

If there is no suitable response found, the sentence: There is nothing special about <entity> is returned.

Parameters:

• entity (Entity) – The entity that the player looks in/on/under.

• player (Entity) – The player that performs the look action.

• location_position (str) – A location preposition: in, on, or under.

• can_not_look_res (Sentence) – The sentence is used if looking at the entity is not possible. For example, “<player> can not look <location_preposition> entity”

Returns:

log – A list of one or multiple sentences. These sentences represent a single response (not multiple valid ones). Inside the look() function, the sentences are merged into a single one using the function cont().

Return type:

list

pydialogue.environment.actions.look_place(entity, player, location_preposition)

Returns the environment response after a player looks in a place.

Parameters:

• entity (Entity) – The entity that the player looks in. The entity has to be a place (have attribute ‘place’).

• player (Entity) – The player that looks.

• location_preposition (str) – The preposition has to be ‘in’ in order to return a non-empty response.

Returns:

A list comprising one sentence indicating the objects that the player sees in the place.

Return type:

list

pydialogue.environment.actions.look_supporter(entity, location_preposition)

Returns the environment response after a player looks on top of the entity.

Parameters:

• entity (Entity) – The entity that the player looks on. The entity has to have the attribute ‘supporter’.

• location_preposition (str) – The preposition has to be ‘on’ in order to return a non-empty response.

Returns:

A list comprising a single sentence outputting what items the entity has on top of it or outputting that the entity contains no items.

Return type:

list

pydialogue.environment.actions.objects_loc_pos(entity, location_preposition)

Returns the entity’s objects that have a specific location preposition.

For example, if the carrot’s location is [‘on’, kitchen_table] then the carrot’s location preposition is ‘on’. If the <entity> is the kitchen_table and the location_preposition is “on”, then the carrot will be part of the returned objects.

pydialogue.environment.descriptions module

This module contains the classes needed to describe an object/entity.

class pydialogue.environment.descriptions.BaseDescription(item=None, mandatory=None, elements=None, cand_elements=None, cand_mandatory=None, random_gen=None)

Bases: object

Generates the elements that are used to describe an entity. For example, the [size, color, type] might be used to describe an apple.

item

The item that is described.

Type:

BaseEntity or Entity

mandatory

A list of True-s and False-s indicating whether the elements (self.elements) used for the description are mandatory. True represents mandatory, and False represents optional.

Type:

list

elements

The list of elements that are used to describe the item. These can be properties and attributes of the item. These elements are selected from the list of candidates.

Type:

list

cand_elements

The list of candidate elements. The self.elements are selected from this list.

Type:

list

cand_mandatory

This list of True-s and False-s indicates whether the candidate elements are mandatory or not.

Type:

list

random_gen

The random generator is used to pick the optional arguments from the list of candidate elements.

Type:

random.Random

filter_candidate_elements(cand)

Selects a set of elements from the list of candidate elements that uniquely describe the item.

Priority is given to the elements that are already seen by the agent. The non-seen elements needed for the entity’s description to be unique are kept to the minimum.

Parameters:

cand (list) – The candidate is a list of two lists. The first list contains the elements, and the second one is a list of False-s and True-s, indicating whether you prefer the elements to be mandatory or not. If you do not have a preference you can leave all values False since in this function a check is done whether the optional arguments need to be mandatory anyway.

Returns:

• elements (list) – A list of elements that are used for the entity’s description

• mandatory (list) – A list of False-s and True-s indicating whether the element is mandatory or not (with True being mandatory).

generate_description(random_pick=True)

Generates and updates the self.elements and self.mandatory if they are empty. Additionally, it can pick which optional elements from the self.elements list to be included.

generate_elements()

Generates the elements and the mandatory list from the list of candidate elements.

mycopy()

Shallow copies the members of the description.

pick_random_elements()

Randomly selects the optional description elements, and it removes the rest of the optional elements from the self.elements and self.mandatory lists. For this function to work, the fields self.elements and self.mandatory must already be filled.

pydialogue.environment.descriptions.permute_list_of_lists(lists, fixed_elements=None, random_gen=None)

Permutes the elements of the individual lists contained in one main list.

Parameters:

• lists (list) – A list that contains multiple lists.

• fixed_elements (list, optional) – The indices that should not be permuted.

• random_gen (random.Random, optional) – A random number generator. It is used to shuffle the elements.

Returns:

lists – The list of lists that have the permuted elements.

Return type:

list

pydialogue.environment.entities module

This module lists the classes that represent the entities/objects in the simulation.

class pydialogue.environment.entities.BaseEntity(properties=None, attributes=None, objects=None, undo_changes=None, random_gen=None)

Bases: object

Creates an entity that is abstract (not part of the world).

For example, in the following sentence: Andy, get a red apple, a red apple is BaseEntity because it can refer to more than one entity in the world. Please refer to the Entity class if you want to create an entity that is part of the world.

properties

The entity can contain properties like size, color, and material.

Type:

dict

attributes

The entity can contain attributes like open, static, place, player, etc. This dictionary always has values None. This is what makes the attributes different from the properties. In the future, we plan to replace the attributes type with a set since the dictionary values are always None.

Type:

dict

objects

The list of other entities the entity might contain. For example, this parameter can be used when the entity is a container, place, supporter, or hollow.

Type:

list

undo_changes

A list of functions that undo the changes made to the entity.

Type:

list

description

The description of the entity. The description uses properties and attributes to describe the entity. Please check the descriptions.Description for more information.

Type:

Description

descriptions

It stores the previously generated descriptions after they are converted to Phrase-s. It is done, so that the phrases can be reused and time can be saved.

Type:

dict

random_gen

The random generator is used instead of random, so that if the dialogue is run again the same generation process will proceed.

Type:

random.Random

describe(elements=None, add_describer=True)

Describes an Entity based on the elements using an instance of the Phrase class.

Parameters:

• elements (list of strings) – A list of property and attribute keys or other strings that describe the Entity. These elements are later converted to a Phrase object. If the elements are not provided, first, a description is generated.

• add_describer (bool) – Whether to add describers for each of the Word-s in the Phrase. Please refer to phrases.description() for more information.

Returns:

phrase – The Phrase that describes the entity.

Return type:

Phrase

generate_description()

Generates a description using all the properties and attributes of the entity. For example, if the entity has a color property ‘blue’ and an attribute ‘container’, the description will be ‘blue container’

get_property(property_name)

Get the property value given the property key. Return an empty string if the property is non-existent.

mycopy(memo)

Makes a copy of the Entity object so that any changes to the original object do not affect the copied one.

Parameters:

memo (dict) – A dictionary that prevents a recursive loop. It stores the entities by id and checks if the current entity is already copied.

Returns:

result – The copied entity.

Return type:

Entity

set_description(description)

Sets the entity description and saves the previous one.

class pydialogue.environment.entities.Entity(world=None, properties=None, attributes=None, objects=None)

Bases: BaseEntity

Creates an instance of an entity that belongs to the physical world.

world

The world that the entity belongs to.

Type:

World

prop_seen

A mapping property_key : property_value, that indicates what properties are revealed in the context.

Type:

dict

prop_seen_neg

A mapping property key => list of property values that are not equal to the correct property value. For example, the entity’s size might be ‘small’, and the list of property values might be [‘medium’, ‘large’]. The properties have to be revealed in the context.

Type:

dict

attr_seen

A mapping attribute : None that indicates what attributes are revealed in the context. In the future, this dictionary can be replaced with a set since all values of the dictionary are None.

Type:

dict

attr_seen_neg

A mapping attribute : None that indicates what attributes the entity does not have. In the future, the dictionary can be replaced with a set since all values of the dictionary are None.

Type:

dict

elem_exists

A set of elements (properties and attributes) that the entity has and that are revealed in the context.

Type:

set

elem_not_exists

A set of elements (properties and attributes) that the entity does not have and that this information is revealed in the context.

Type:

set

change_world(new_world)

Changes the world that the entity is part of.

generate_description(cand_descriptions=None, random_gen=None, relaxed=True)

Generates a description of the entity.

Parameters:

• cand_descriptions (list, optional) – A list of candidate descriptions (instances of the class BaseDescription).

• random_gen (random.Random, optional) – The random_gen makes sure that the dialogue always has the same randomization in case the dialogue is restarted.

• relaxed (bool, optional) – If False, when generating the descriptions, priority is given to the descriptions generated for the first time (the agent has not seen any of the entity’s properties or attributes). Otherwise, priority is given to the descriptions where the agent has seen some properties/attributes.

Returns:

description – The description of the entity.

Return type:

Description

mycopy(memo)

Makes a copy of the Entity object so that any changes to the original object do not affect the copied one.

Parameters:

memo (dict) – A dictionary that prevents a recursive loop. It stores the entities by id and checks if the current entity is already copied.

Returns:

result – The copied entity.

Return type:

Entity

select_unique_descriptions(cand_descriptions=None)

Selects the unique descriptions from the candidate descriptions.

If the candidate descriptions are not provided, they are instantiated from the world.all_description_objects.

Parameters:

cand_descriptions (list) – A list of BaseDescription instances that are used to describe the world’s entities.

Returns:

• seen (list) – The list of unique descriptions where all the description’s elements are seen by the players.

• not_seen (list) – The list of unique descriptions where all the description’s elements are not seen by the players.

• partially_seen (list) – The list of unique descriptions where some of the description’s elements are seen by the players.

top_location()

Compute the top location of an item. For example, if the item is in a container and the container is in a room, then the top location of the item is the room.

validate_reachability(player, location_entity, neg_res=None)

Checks whether the entity (self) is reachable to the player at a specific location.

Parameters:

• player (Entity) – The player that executes the action.

• location_entity (Entity) – The location entity where self is found.

• neg_res (Sentence) – The negative response in case the entity is not reachable. For example, <player> can not get <self>.

Returns:

log – Returns an empty list if the item is reachable to the player at the location. If the entity is not reachable, return the negative response concatenated together with the reason why.

Return type:

list

pydialogue.environment.helpers module

This module provides the functions that help all other modules in this folder to do their operations.

pydialogue.environment.helpers.check_can_not(sentences, verb)

Checks whether a Sentence from a list of sentences contains this pattern: “can not <verb>.”

pydialogue.environment.helpers.check_desc_collision(entity, elements)

pydialogue.environment.helpers.extract_tries_sent(sentence, world)

Extracts the inner sentence from the following one:

<player> tries <inner_sentence>

In the following example: “Hannah tries changing the toy’s color”, the “changing the toy’s color” is extracted.

pydialogue.environment.helpers.item_path(item)

Returns all locations of the item that lead to the top location. The list includes the item itself. For example, if the item is located on a shelf in a kitchen’s drawer, the path will be: [item, shelf, kitchen’s drawer, kitchen].

pydialogue.environment.helpers.join_el_conn(elements, connector, last_conn=None)

Adds the connector between the elements of the lists. The last_conn connects the last two elements, which might differ from the connector. The default one is ‘and’. This function returns [elem1, connector, elem2, connector, elem3, last_conn, elem4] if the list has 4 elements. This is useful in responses where you want to list objects in a sentence like: “The <entity> contains the toy apple, toy carrot, and a book”, where the last connector differs.

Module contents