pydialogue.generation package

Submodules

pydialogue.generation.dialogue module

This module contains the Dialogue class, which controls the dialogue between one or more agents in the world.

class pydialogue.generation.dialogue.Dialogue(dia_generator=None, policies=None, goal_generator=None, entities_descriptions=None)

Bases: object

This class controls the dialogue between one or more participants.

random_seed

The random seed is used to initialize the random generator. This seed is randomly selected for each new dialogue.

Type:

int

random_gen

The random generator is seeded with the same seed before each run. It makes sure that the dialogue can be run again and will output the same utterances. For example, the environment can provide several responses, each of which can change the course of the dialogue. The random generator will select the same response each time the dialogue is run.

Type:

random.Random

dia_generator

This instance is responsible for generating dialogues and executing the dialogue utterances.

Type:

DialogueGenerator

policies

The participants’ policies. The policies should follow the base_policies.Policy interface.

Type:

list

utterances

The list of dialogue utterances uttered by the policies.

Type:

list

curr_speaker

The player whose self is executed on the current turn.

Type:

Entity

counter

The number of turns taken in the dialogue. One turn is when all participants finish uttering.

Type:

int

next_policy_id

The id of the next self to be executed. The id starts from 0 to len(self.policies)-1

Type:

int

max_episode_length

The maximum number of utterances the agent is allowed to take.

Type:

int

goal_generator

Generates the current dialogue’s goal. Since the goal can change over time, there is a goal generator that generates a new goal after each utterance. There is a goal generator instead of a single goal due to the non-deterministic nature of the participant responses. For example, the user might decide to change the request, or the environment might have a list of valid responses that reveal different kinds of information, of which one is randomly selected.

Type:

Generator

use_generator

The current rule-based policies return both the utterance and the goal of the agent. So it will be useful not to run the goal generator if the self returns the same goal. If this field is False, the goal generator is not run. Otherwise, the goal generator is used.

Type:

bool

goal

The goal of the dialogue.

Type:

Goal

dialogue_over

True if the dialogue is finished. False if the dialogue is in progress.

Type:

bool

curr_reward

The agent’s reward. 0 means dialogue is still in progress, 1 success, and -1 failure.

Type:

int

entities_descriptions

A dictionary with the key being an Entity and the value is the entity’s Description. The entity’s description is used whenever the entity appears in the dialogue.

Type:

dict

max_safety

The max_safety is used to stop the dialogue just in case some rule-based self goes into an infinite recursion. The default is 20 * (1 + 6) * 4 * 2. The calculation is described in the next few sentences. The number of items from the easy and hard environment (20) times the longest path between two points (including opening doors) plus one for executing the action. (1+6) This is considering actions like get <a> <item>. The agent might need to visit all items that match the same <a> <item> description. (4) So, we multiply the maximum number of similar items by 2 for safety.

Type:

int

add_policies(policies)

Adds agent policies to the dialogue.

evaluate_goal()

Executes the current goal and sets the current reward.

If the goal evaluates to 1, that indicates success, and the reward is set to 1. In case the dialogue is over and the goal is not a success, then the evaluation is set to -1 (failure).

generate_new_goal(**params_replace)

Generates new goal by executing the goal generator

get_player_policies(player)

Fetches all the policies that belong to a player.

get_player_utters(player)

Fetches all the utterances that belong to a player.

get_players()

Fetches all the participants of the dialogue.

get_utterances()

Gets the dialogue utterances.

is_over()

Sets a flag whether the dialogue is over. The dialogue is over when the reward is 1 or -1 or when the counter exceeds the maximum episode length. All agents have to finish with their turns before the dialogue is over.

player_utters(utter)

Updates the dialogue generator with the new utterance and returns: the utterance together with the environmental response, the reward for uttering, whether the dialogue is over, and other information. For more details, please check the step docstring.

recover_state(state)

Recovers the state of all class members that change with time

replace_player_policies(new_policies)

Replaces the player policies with new ones. This function is useful when evaluating machine learning models because the agent’s rule-based self is replaced with the model-based.

reset_descriptions()

Resets all the world’s entities’ descriptions and sets the predefined descriptions (in case they exist). It also updates the descriptions’ random generator to make sure that the dialogue outputs the exact same utterances in case it is run again.

run(fake=False)

Runs the dialogue by giving a turn to each of the participant policies in the order as they appear in the list self.policies. When all policies are executed, one cycle is complete.

save_state()

Saves the state of all class members that change with time

step()

Steps into the current self and executes it.

Returns:

• obs (list) – List of observations/sentences that represent the environment response to the player’s utterance.

• reward (int) – The reward that the player receives after uttering.

• dialogue_over (bool) – Indicates whether the dialogue is finished or still ongoing.

• info (dict) – Other information.

pydialogue.generation.file_list_db module

This module contains the FileListDb class that stores sentences and flushes them in a file when needed.

class pydialogue.generation.file_list_db.ListDb(elements=None, num_flush=None)

Bases: object

Extends the functionality of a list by:

• flushing the elements if the list reaches a certain number of elements.

• copying the elements before adding them to the list (The elements should have a mycopy method)

This class is useful for storing the context sentences so that RAM does not get full as the simulation runs.

elements

The elements of the list. The elements can be of any type.

Type:

list

num_flush

The number of elements to be removed when the flush function is called.

Type:

int

num_elements

The number of elements that the list of elements has.

Type:

int

add(new_elements, serialize=False)

Adds the elements to the list. If the parameter serialize is set to True, it copies them using the mycopy method before adding them. Copying is useful when you would like to preserve the Entity state since the entities change over time.

flush()

Removes the first self.num_flush elements from the list.

get(last_num_elements)

Gets the last number of elements from the list.

recover_state(state)

Recovers the state of the list without losing the original reference.

save_state()

Returns a copy of the configuration of the list

separate_slice(slice_)

Separates a slice start:step:stop into start, step, stop.

class pydialogue.generation.file_list_db.StringListDb(file_name=None, elements=None, num_flush=None)

Bases: ListDb

Extends the functionality of a ListDb by:

• storing the elements in a file (The elements should have the to_string method if they are not strings).

• flushing the elements in a file if the list reaches a certain number of elements.

• fetching and deleting the elements in the file.

file_name

The file name where the elements will be saved when the flush function is called.

Type:

str

flush()

Removes the first self.num_flush elements from the list and saves them to a file if the filename is available.

get(last_num_elements)

Gets the last number of elements from the list. This function is faster compared to __getitem__ when fetching the last_num_elements because it fetches the elements from the end of the file.

load_slice_from_file(start_index, end_index, step)

Loads a slice of the list of elements stored in the file self.file_name. The elements are taken from start_index to end_index. If the step is available, each step-th element is taken.

remove_slice_from_file(start_index, end_index, step)

Removes a slice of the list of elements stored in the file self.file_name. The elements removed are from start_index to end_index, skipping each <step> element.

reverse_load_from_file(num_elem)

Loads the last num_elem from file by iterating through the file in reversed order.

save_to_file(num_elem)

Saves the last <num_elem> elements to a file.

pydialogue.generation.goal_generators module

This module lists all the classes that generate the goals of the dialogue.

class pydialogue.generation.goal_generators.GoalGenerator(policy)

Bases: object

A simple goal generator that generates the agent’s goal (class goals.Goal). The agent’s goal can change during the dialogue, so the goal generator is required.

policy

The rule-based self that returns the self’s goal.

Type:

Policy

execute()

The current rule-based agent policies return the next player’s utterance and their goal. We use the self’s get_goal function to fetch the goal.

recover_state(state)

Recovers the state of the goal generator by recovering the self state.

replace_dialogue(new_dialogue)

In case the self is used in a different dialogue, this function allows replacing the dialogue.

save_state()

Saves the state of the goal generator by saving the self state.

pydialogue.generation.helpers module

This module contains functions that are used by all other modules in this folder.

pydialogue.generation.helpers.configure_logging(filename, level=None, format_=None)

Configures logging to output errors only to a file, not the Colab screen.

pydialogue.generation.helpers.configure_logging_old(filename, level=None, format_=None, force_=True)

Configures the level and format of the logging.

pydialogue.generation.helpers.create_unk_item(item, similar_elements, item_description=None)

Creates an item that is not part of the world based on the elements of a concrete item that is part of the world. Additionally, if the new item’s description is not provided, it is taken from the <item>’s description.

Parameters:

• item (Entity) – The concrete item that is used to fetch the elements and potentially the item’s description that is needed for the new item.

• similar_elements (list) – A list of properties and attributes that will be fetched from the <item>.

• item_description (BaseDescription) – The item_description is used for the generate_description(…) method which dictates the order and the elements used in the item’s description.

Returns:

unk_item – The new item is not part of the world and has the “abstract” attribute to indicate the fact.

Return type:

BaseEntity

pydialogue.generation.helpers.extract_knowledge(stat, memo=None)

Extracts the meta sentences from a Sentence or a Phrase. It includes the meta sentences from all inner sentences, phrases or words that a phrase or sentence might contain.

pydialogue.generation.helpers.find_policy(policy_db, policy_class)

Find the self from the list of policies based on the self class

pydialogue.generation.helpers.generate_primitive_structure(random_gen, primitive_templates)

Returns a list that contains a single tuple. The tuple’s first value is the string ‘primitive’ and the second is a randomly selected template (function) from a list of primitive templates.

pydialogue.generation.helpers.generate_property_val(dia_generator, candidate_keys)

Selects a random key from a list of property keys and generates a random property value.

pydialogue.generation.helpers.make_dynamic_copy(pol)

Makes a new instance of the self class and assigns the same class member references as the old one.

pydialogue.generation.helpers.reduce_and_extract(sentences, add_original=False)

Reduces the sentences and extracts the meta sentences from them. If the add_original is True, the original sentences are added to the final list.

pydialogue.generation.helpers.unk_from_desc(random_gen, item)

Creates an abstract item from a concrete item. The new item is created using some description elements of the concrete item.

pydialogue.generation.mappers_database module

This module provides the class that represents a database of all describer mappers. It has functions that can convert an arbitrary describer into a sentence.

class pydialogue.generation.mappers_database.MapperDatabase(slist=None)

Bases: object

This class is used for generating a sentence from a list of describers.

slist

The database comprises a list of mappers that map the describers to a sentence.

Type:

list, optional

query_primitive_sentence(describers, speaker=None)

Queries the database for a primitive sentence from a list of describers. A primitive sentence is one that has a single predicate, or if it consists of more than one predicate then the constituent sentences are independent. The complex sentences are handled in the query_sentence function.

Parameters:

• describers (list) – List of describers used for querying the database.

• speaker (Entity, optional) – The agent that the matching sentences belong to.

Returns:

matching_sentences – A list of matched sentences.

Return type:

list

query_sentence(describers, speaker=None, last_match=-1)

Queries a sentence from the database based on the given describers. It queries both primitive and complex sentences. The primitive sentences are explained in the query_primitive_sentence function. A complex sentence consists of one independent and one or more dependent sentences.

Parameters:

• describers (list) – List of instances of the class Describer.

• speaker (Entity, optional) – The person that utters the sentence.

• last_match (int, optional) – The index of the sentence to select in case there are multiple matches in the database.

Returns:

new_sent – The queried sentence.

Return type:

Sentence

register(desc_mappers)

Registers the describer mapper in the database.

Parameters:

desc_mappers (list or function) – The describer mapper/s to be added in the database.

Return type:

None.

pydialogue.generation.param_generators module

This module contains functions that generate random parameters for the template functions.

pydialogue.generation.param_generators.candidate_prop_keys(curr_params)

Fetches all property keys from the world except var_name and door_to

pydialogue.generation.param_generators.random_agent(curr_params)

pydialogue.generation.param_generators.random_determiner_a(curr_params)

pydialogue.generation.param_generators.random_dir(curr_params)

pydialogue.generation.param_generators.random_item(curr_params)

Generates a random item from the list of objects in the world. If the determiner_a is True, the world’s object should be converted to an abstract object. The abstract object can not be uniquely determined. For example, the flour container will be converted to a flour container.

pydialogue.generation.param_generators.random_location(curr_params)

Generates a random location. The location can be an object. Some templates allow None to be the location, meaning the location is not provided.

pydialogue.generation.param_generators.random_param_value(curr_params, param_name)

Fetches a parameter from the dictionary of parameters and generates a random value from it. The parameter should be an iterable.

Parameters:

• curr_params (dict) – A dictionary that contains the parameters. It is a mapping parameter_name: parameter_value.

• param_name (str) – The name of the parameter.

Returns:

A random value selected from the iterable.

Return type:

any

pydialogue.generation.param_generators.random_property_val(curr_params)

Generates random property value for a given property key. It takes one value from the list of property values that are suitable for the property key. For example, for the property key color, it takes one of the following ‘red’, ‘blue’, ‘green’, etc. Later, it takes ten values that are not suitable for the property key. For the given example, this can be ‘size’ like ‘small’ or ‘big’. Finally, it returns a single random value from the list of 11 values.

The selection is done this way, so that the agent can see a variety of property values, not only the ones that are suitable.

pydialogue.generation.param_generators.random_user(curr_params)

Generates a random player from the list of players except the main player. Therefore, the main player can not issue requests.

pydialogue.generation.param_generators.random_world_list(curr_params, member_name)

Fetches an iterable member of the class World and generates a random value from it.

For example, the member can be players, so a random value will be selected from the world.players list.

Parameters:

• curr_params (dict) – A dictionary that contains the parameters. It is a mapping parameter_name: parameter_value.

• member_name (str) – The name of the member that will be fetched from the class World.

Returns:

A random value selected from the world’s member.

Return type:

any

pydialogue.generation.templates module

This module contains functions called templates that generate different dialogue types.

pydialogue.generation.templates.action_item(dia_generator, user, agent, user_pol_class, agent_pol_class, item, location=None, location_position=None, entities_descriptions=None)

Creates a dialogue between a user, an agent and the environment. The user issues a request using the user’s self to the agent in the following manner:

<user> says: <agent> <action> (preposition) <item> <preposition> <location>

For example:

Jim says: John look in the toys container in the bedroom.

In this case, the user_pol_class is user_policies.LookItemPolicy The goal of the dialogue is for the agent to fulfill the user’s request by making several utterances.

Parameters:

• dia_generator (DialogueGenerator) – The class used for generating new dialogues.

• user (Entity) – The user that issues the request.

• agent (Entity) – The agent that needs to fulfill the user’s request.

• user_pol_class (type) – The class type that is used to create an instance of the user self. The user policies can be found in the user_policies.py file.

• agent_pol_class (type) – The class type that is used to create an instance of the agent self. The agent policies can be found in the agent_policies.py file.

• item (Entity) – The item that the agent acts upon.

• location (Entity, optional) – The supposed location of the item. It does not have to be the correct one.

• location_position (str, optional) – The preposition that refers to the location. For example. in, under or on.

• entities_descriptions (dict (Entity : BaseDescription)) – A description for each of the entities that are part of the dialogue. Each entity can have different description. For example, the toys container can be described as the static container or the red container. If left None, entities descriptions will be automatically generated as the dialogue runs.

Returns:

dialogue – Returns the dialogue that is ready to be run.

Return type:

Dialogue

pydialogue.generation.templates.drop_item(dia_generator, user, agent, item, location=None, location_position=None, entities_descriptions=None)

pydialogue.generation.templates.get_item(dia_generator, user, agent, item, location=None, location_position=None, entities_descriptions=None)

pydialogue.generation.templates.go_direction(dia_generator, user, agent, direction, entities_descriptions=None)

Creates a dialogue between a user, an agent and the environment. The user issues a request to the agent in the following manner:

<user> says: <agent> go <direction>

The goal of the dialogue is for the agent to fulfill the user’s request.

Parameters:

• dia_generator (DialogueGenerator) – The class used for generating new dialogues.

• user (Entity) – The user that sends the request.

• agent (Entity) – The agent that needs to fulfill the user’s request.

• direction (str) – The direction where the agent should go. For example: north, east, northeast … The list of directions can be found in dia_generator.world.directions.

• entities_descriptions (dict (Entity : BaseDescription)) – A description for each of the entities that are part of the dialogue. Each entity can have a different description. For example, the toys container can be described as the static container or the red container. If left None, entities’ descriptions will be automatically generated as the dialogue runs.

Returns:

dialogue – Returns the dialogue that is ready to be run.

Return type:

Dialogue

pydialogue.generation.templates.go_location(dia_generator, user, agent, item, location=None, location_position=None, entities_descriptions=None)

pydialogue.generation.templates.init_dialogue(dia_generator, user_policy, agent_policy, entities_descriptions=None)

Creates and initializes the dialogue.

Parameters:

• dia_generator (DialogueGenerator) – The dialogue generator that was used to generate the dialogue.

• user_policy (UserPolicy) – The user self. The user issues the request to the agent.

• agent_policy (AgentPolicy) – The agent’s self. The agent should satisfy the user’s request.

• entities_descriptions (dict (Entity : BaseDescription)) – A description for each of the entities that are part of the dialogue. Each entity can have a different description. For example, the toy’s container can be described as “the static red container” or “the red openable container”. If left None, entities’ descriptions will be automatically generated as the dialogue runs.

Returns:

dialogue – The initialized dialogue.

Return type:

Dialogue

pydialogue.generation.templates.item_prop_revealed(dia_generator, item, property_key, property_val, entities_descriptions=None)

pydialogue.generation.templates.look_item(dia_generator, user, agent, item, location=None, location_position=None, entities_descriptions=None)

Module contents