pydialogue.language package

Submodules

pydialogue.language.components module

This module provides the classes that represent the language elements like word, phrase or sentence. Moreover, it contains the classes needed for the PropBank arguments.

class pydialogue.language.components.Arg(value=None, part=None)

Bases: object

The Arg class stores the PropBank argument.

value

The value of the argument carries the semantics of the PropBank argument. For example, in the sentence “Andy sees the small ball, the big ball, and the red toy.”, the Arg-PPT’s value is [small_ball, big_ball, red_toy]. The connectors between the items are not important for the semantics and are left out in the value but included in the part. Please find more information about how the values are computed in our paper.

Type:

any

part

The language part carries the syntax of the PropBank argument. It includes all words and connectors that appear in the sentence. For the example above, the language part of Arg-PPT is:

[lc.Phrase([lc.Word('the'), lc.Word('small'), lc.Word('ball')]), lc.Word(",") ... ]

Type:

Union[Word, Phrase, Sentence, list, set], optional

mycopy(memo)

Copies the self.value and the self.part. The memo is used in order to prevent copying the same member in case there is a circular relationship between two members.

class pydialogue.language.components.Customizer(func, func_params)

Bases: object

The customizer uses a function to modify the Word, Phrase, or Sentence.

func

The function used for customizing.

Type:

function

func_params

The function parameters needed for the function.

Type:

dict

mycopy(memo)

Copies the func_params dictionary recursively.

run(custom_params=None)

Runs the customizer by invoking self.func with the function parameters. (self.func_params) The custom_params can temporarily replace some func_params.

class pydialogue.language.components.Describer(args=None, prune=True)

Bases: object

The describer represents the list of PropBank arguments extracted from a sentence.

The dictionary is used to store the args, so they can be quickly fetched by their name. An example of annotating the sentence “Hans has the small ball and the red ball” is:

args['Arg-PPT'] = Arg(world.player2)
args['Rel'] = RelArg('has')
args['Arg-PRD'] = Arg([world.small_ball, world.red_ball])

Additionally, the language parts can be added to the arg by calling helpers.convert_obj_to_part.

To see how to annotate the sentence, please check the PropBank guidelines.

For automatic semantic labeling, you can check the Verbnet Parser. Additionally, we modified the argument keys such that the numbers in the names of PropBank arguments are ignored so that the order of the arguments is no longer important. This way, the grammatical structure of the sentence is left out, and the focus is strictly on the semantics. Please check our paper to see all the modifications that we did.

args

The dictionary of arguments.

Type:

dict

get_arg(key, _type=1)

Gets the argument from self.args

Parameters:

• key (str) – The key is used to fetch the argument from the dictionary. The argument keys either start with Arg- (for the main args) or AM- (for the modifier args). The PropBank contains the full list of argument types.

• _type (int, optional) – The type indicates whether the whole argument is fetched (type=0), the value (type=1) or just the part(type=2)

Returns:

res – The desired argument.

Return type:

any

mycopy(memo)

Copies the members of the class Describer. The memo serves to prevent copying the same member in case there is a circular relationship between two members.

prune_none_args()

Removes the args that have value None

class pydialogue.language.components.Phrase(parts=None, meta_sent=None, customizers=None)

Bases: object

A class that represents a phrase. The phrase lacks both a subject and a verb.

parts

A list of instances of type Word and Phrase. An example of a phrase containing another phrase is “under the old wooden table,” where the “old wooden table” is the embedded phrase.

Type:

list

meta_sent

The meta-sentences provide additional information that can be inferred from the phrase itself or the context where the phrase is used. For the example above, the meta-sentence can be “The old wooden table’s material is not plastic.”

Type:

list, optional

customizers

Dictionary with the key being the customizer name and the value being an object of type Customizer. The customizer transforms the phrase into a different one. An example is ‘the red door’, which can be transformed into ‘the wooden door’.

Type:

dict, optional

mycopy(memo)

Copies all the attributes of the class Phrase recursively.

remove_nones()

Remove the words from the list of parts that are None. Moreover, if the parts contain another list, merge it with the original one.

run_customizer(customizer_name, replace_params=None)

Run customizer with parameters (if present) that replace the customizer default ones.

to_string()

Converts the phrase into a string.

class pydialogue.language.components.RelArg(value=None, part=None)

Bases: Arg

Argument for the verb in the sentence (PropBank Arg-Rel). The addition to the Arg class is the infinitive which is useful for comparing two arguments regardless of the conjugated form of the verb. The verb tense is still preserved.

compute_infinitive()

Computes the infinitive of the verb and conjugates it in its tense form.

mycopy(memo)

Copies the self.value and the self.part. The memo is used in order to prevent copying the same member in case there is a circular relationship between two members.

class pydialogue.language.components.Sentence(parts=None, meta_sent=None, customizers=None, describers=None, speaker=None, trusted_source=None)

Bases: Phrase

A class that represents a phrase. The sentence contains both a subject and a verb.

describers

A list of describers that represent the PropBank annotation of the sentence. If the sentence is compound, it has more than one verb and, therefore, more than one describer.

Type:

list, optional

speaker

The person who utters the sentence.

Type:

Entity, optional

trusted_source

The trusted source indicates whether the information the sentence conveys can be trusted. For example, if the machine learning model is imperfect, the utterances can not be trusted.

Type:

bool, optional

mycopy(memo)

Copies the speaker and the describers of the Sentence.

reduce()

Calls the “reduce” customizer if present. If not, the same sentence is returned.

The “reduce” customizer is applied if you want to simplify the sentence so that each describer argument has the least amount of elements.

For example, the sentence “Andy has the red ball and the small ball” can be reduced to two sentences: “Andy has the red ball” and “Andy has the small ball”. The third describer argument Arg-PPT had [red_ball, small_ball] reduced to two sentences that have a single value in the Arg-PPT.

class pydialogue.language.components.Word(string_value, meta_sent=None, customizers=None)

Bases: object

A class that represents a word.

string_value

A single word.

Type:

str

meta_sent

A list of sentences that describe the word or provide additional information. An example can be the word ‘red’, and the meta sentence can be Red is a color. It can also be used to clarify the meaning of the word based on the context.

Type:

list, optional

customizers

Dictionary with the key being the customizer name and the value being an object of type Customizer. The customizers can transform the word into a different word or conjugated form of the word. An example of a word customizer can be a verb conjugator.

Type:

dict, optional

mycopy(memo)

Copies the members of the class Word. The memo serves to prevent copying the same member in case there is a circular relationship between two members.

run_customizer(customizer_name, additional_params=None)

Runs the customizer with parameters (if present) that replace the customizer default ones.

to_string()

Converts the Word object into string

pydialogue.language.components.check_and_download(resource, path)

pydialogue.language.components.conjugate_verb(verb)

Converts the verb first into its base form and later into its tense form. For example, for the verb “goes,” the result is the verb “go”.

Parameters:

verb (str) – The verb to be conjugated.

Returns:

conjugated_verb – The conjugated verb.

Return type:

str

pydialogue.language.components.mycopy_el(elem, memo)

Copy the elements that contain the mycopy function. If the element is a list, set, dict then the copying is done recursively.

Parameters:

• elem (Union[set, dict, list, objects containing mycopy]) – The element to be copied.

• memo (dict) – The dictionary memorizes whether an element has been copied already. This is done in case there are cyclic relations between two objects.

Returns:

copied_el – The copied element.

Return type:

Union[set, dict, list, objects containing mycopy]

pydialogue.language.components.prepare_hash(obj)

Recursively converts the dictionaries and the sets into frozen sets. The lists are also converted into tuples and the tuples are also prepared because some tuples might contain mutable objects like lists.

pydialogue.language.components.retrieve_inflection(verb, tag)

Caches the verb’s inflection based on the tag. The tag can be VB, VBD, VBG, VBN, VBP, VBZ. If the inflection is already cached, the token is returned.

pydialogue.language.components.retrieve_pos(verb)

Caches the verb’s (str) part-of-speech (pos) tag.

If the verb is mistakenly tagged as something else, we find the correct tag by going through all inflections. If the verb is already cached, the token is returned.

pydialogue.language.components.verb_inf(verb)

Finds the infinite form of the verb.

pydialogue.language.components.verb_tense(verb)

Returns the Part-of-speech (POS) tag of the verb. We use the POS tag to determine the tense of the verb.

pydialogue.language.desc_mappers module

This module contains all functions that convert a specific Describer into the corresponding Sentence.

We decided to put a list of describers as an argument for each of the functions below, even though some functions use only one describer. The reason is to be consistent among all functions.

pydialogue.language.desc_mappers.be(describers, no_parts=True)

Calls the sentences.be() with the arguments from the first Describer in the list of describers. If the argument AM-DIS argument is present, it calls the queries.be() instead.

pydialogue.language.desc_mappers.cont_connector(describers, database, connector=None)

Creates multiple sentences from describers and joins them using a connector like “and”. The end result is a single compound sentence.

pydialogue.language.desc_mappers.drop(describers, no_parts=True)

Calls the sentences.drop() with the arguments from the first Describer in the list of describers. If the argument AM-DIS argument is present, it calls the queries.drop() instead.

pydialogue.language.desc_mappers.empty(describers, no_parts=True)

Creates an empty sentence that does not have any words. An empty sentence is identified by having no verb. The no_parts parameter is used to be consistent with the other desc mappers.

pydialogue.language.desc_mappers.get(describers, no_parts=True)

Calls the sentences.get() with the arguments from the first Describer in the list of describers. If the argument AM-DIS argument is present, it calls the queries.get() instead.

pydialogue.language.desc_mappers.go(describers, no_parts=True)

Calls the sentences.go() with the arguments from the first Describer in the list of describers. If the argument AM-DIS argument is present, it calls the queries.go() instead.

pydialogue.language.desc_mappers.have(describers, no_parts=True)

Creates a sentences.have() <pydialogue.language.sentences.have> from the first Describer of a list of describers.

pydialogue.language.desc_mappers.know(describers, no_parts=True)

Creates a sentences.know() <pydialogue.language.sentences.know> from the first Describer of a list of describers.

pydialogue.language.desc_mappers.look(describers, no_parts=True)

Calls the sentences.look() with the arguments from the first Describer in the list of describers. If the argument AM-DIS argument is present, it calls the queries.look() instead.

pydialogue.language.desc_mappers.permit(describers, no_parts=True)

Creates a sentences.permit() <pydialogue.language.sentences.permit> from the first Describer of a list of describers.

pydialogue.language.desc_mappers.reveal(describers, no_parts=True)

Creates a sentences.reveal() <pydialogue.language.sentences.reveal> from the first Describer of a list of describers.

pydialogue.language.desc_mappers.say(describers, no_parts=True)

Creates a func:sentences.say() <pydialogue.language.sentences.say> from the first Describer of a list of describers

pydialogue.language.desc_mappers.see(describers, no_parts=True)

Creates a sentences.see() <pydialogue.language.sentences.see> from the first Describer of a list of describers

pydialogue.language.desc_mappers.tries(describers, no_parts=True)

Creates a sentences.tries() <pydialogue.language.sentences.tries> from the first Describer of a list of describers.

pydialogue.language.desc_mappers.validate_describers(func)

pydialogue.language.describers module

This module offers a list of functions that create instances of Describer-s.

pydialogue.language.describers.be(topic=(None, None), rel=(None, None), neg=(None, None), comment=(None, None), prune=True)

Creates a Describer for the sentences.be()

pydialogue.language.describers.drop(player=(None, None), mod=(None, None), neg=(None, None), rel=(None, None), entity=(None, None), location=(None, None), prune=True)

Creates a Describer for the sentences.drop()

pydialogue.language.describers.get(receiver=(None, None), mod=(None, None), neg=(None, None), rel=(None, None), thing_gotten=(None, None), giver=(None, None), prune=True)

Creates a Describer for the sentences.get()

pydialogue.language.describers.go(goer=(None, None), mod=(None, None), neg=(None, None), rel=(None, None), direction=(None, None), start_point=(None, None), end_point=(None, None), prune=True)

Creates a Describer for the sentences.go()

pydialogue.language.describers.have(owner=(None, None), rel=(None, None), neg=(None, None), possession=(None, None), location=(None, None), prune=True)

Creates a Describer for the sentences.have()

pydialogue.language.describers.issue(issuer=(None, None), mod=(None, None), neg=(None, None), rel=(None, None), thing_issued=(None, None), prune=True)

Creates a Describer for the sentences.issue()

pydialogue.language.describers.know(knower=(None, None), neg=(None, None), rel=(None, None), fact_known=(None, None), prune=True)

Creates a Describer for the sentences.know()

pydialogue.language.describers.look(player=(None, None), mod=(None, None), neg=(None, None), rel=(None, None), thing_looked=(None, None), prune=True)

Creates a Describer for the sentences.look()

pydialogue.language.describers.permit(allowed_agent=(None, None), neg=(None, None), rel=(None, None), action_allowed=(None, None), allower=(None, None), prune=True)

Creates a Describer for the sentences.permit()

pydialogue.language.describers.reveal(revealer=(None, None), truth_cond=(None, None), neg=(None, None), rel=(None, None), prune=True)

Creates a Describer for the sentences.reveal()

pydialogue.language.describers.say(user=(None, None), neg=(None, None), rel=(None, None), utterance=(None, None), agent=(None, None), prune=True)

Creates a Describer for the sentences.say()

pydialogue.language.describers.see(player=None, neg=(None, None), rel=(None, None), entity=(None, None), location=(None, None), prune=True)

Creates a Describer for the sentences.see()

pydialogue.language.describers.tries(entity_trying=(None, None), mod=(None, None), neg=(None, None), rel=(None, None), thing_tried=(None, None), prune=True)

Creates a Describer for the sentences.tries()

pydialogue.language.describers.want(wanter=(None, None), neg=(None, None), rel=(None, None), thing_wanted=(None, None), prune=True)

Creates a Describer for the sentences.want()

pydialogue.language.helpers module

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

pydialogue.language.helpers.auto_fill(args_ignored_ids=None, args_ignored_keys=None)

Creates a decorator that fills the missing argument parts in the language.sentences functions and the language.queries modules. Each argument of the functions is a tuple (argument_value, argument_part). If the argument_value is the only one provided, the argument_part is automatically filled, and the necessary tuple is created.

Parameters:

• args_ignored_ids (list, optional) – The indices of the arguments that should not be filled. The indices start from 0, 1, … 0 represents the first argument in the function.

• args_ignored_keys (list, optional) – The keys of the arguments that should not be filled. The keys are the argument names. For example, the argument name “player” in sentences.go.

Returns:

The function decorator.

Return type:

function

pydialogue.language.helpers.convert_obj_to_part(obj)

Converts the object to a language component (Word, Phrase, or list).

pydialogue.language.helpers.join_parts_with_connector(parts, connector)

Adds a Word(connector) between each of the language components (Word, Phrase, or Sentence).

pydialogue.language.helpers.reduce_sentences(sentences, memo=None, add_original=False)

Reduce the sentences to simpler ones. Please check the components.Sentence.reduce for more information.

Parameters:

• sentences (list) – The list of sentences to be reduced. Each sentence should be an instance of the class Sentence and have the reduce method implemented or should define the field sent.customizers[‘reduce’] by creating an instance of the class Customizer. If the reduce method is not implemented, the same sentence is returned.

• memo (dict, optional) – A dictionary that prevents reducing the same sentence twice.

• add_original (bool, optional) – Whether to add the original/unreduced form of the sentence to the list.

Returns:

reduced – The list of reduced sentences.

Return type:

list

pydialogue.language.helpers.returns_same(sentence)

Returns the same object.

pydialogue.language.phrases module

This module contains the functions that create a specific phrase.

pydialogue.language.phrases.description(entity, elements, add_describer=True)

Generates a description for the entity based on its attributes and properties.

Parameters:

• entity (Entity) – The entity to be described.

• elements (list) – A list of attributes and properties that belong to the entity. If the entity does not have a specific attribute or property, but the element is a string, it is still added as lc.Word.

• add_describer (bool, optional) –

  Whether to add meta sentences/additional information to each lc.Word or lc.Phrase. Examples of meta sentences added to the phrase “red static bathroom” are:

  • The red static bathroom’s color is red.

  • Red is a color.

  • The red static bathroom is static.

Returns:

phrase – The phrase that describes the entity.

Return type:

Phrase

pydialogue.language.queries module

This module provides functions that create request sentences from parameters.

pydialogue.language.queries.cont_connector(sentences, speaker=None, connector=None)

Connects multiple requests in a single compound request using a connector.

pydialogue.language.queries.drop(tmp=(None, None), player=(None, None), neg=(None, None), rel=(None, None), entity=(None, None), prepos_location=(None, None), speaker=None)

Creates a request for the verb drop in the following format:

<tmp> <player> (neg) <drop> <entity> <prepos_location>

where prepos_location refers to the target location. For example, “Max, drop the cup on the table.”

pydialogue.language.queries.get(tmp=(None, None), player=(None, None), neg=(None, None), rel=(None, None), entity=(None, None), prepos_location=(None, None), speaker=None)

Creates a request for the verb get in the following format:

<tmp> <player> (neg) <get> <entity> <prepos_location>

For example, “Hannah, get the book on the shelf.”

pydialogue.language.queries.go(tmp=(None, None), player=(None, None), neg=(None, None), rel=(None, None), direction=(None, None), source_location=(None, None), target_location=(None, None), speaker=None)

Creates a request for the verb go in the following format:

<tmp> <player> (neg) <go> <direction> <source_location> <target_location>

For example, “Andy, go north from the guest room.”

pydialogue.language.queries.look(tmp=(None, None), player=(None, None), neg=(None, None), rel=(None, None), thing_looked=(None, None), speaker=None)

Creates a request for the verb look in the following format:

<tmp> <player> (neg) <look> <thing_looked> <item_location>

For example, “Max, look in the clothing drawer in the bedroom.”

pydialogue.language.sentences module

This module provides functions that create a statement.

pydialogue.language.sentences.Wh_question(comment, rel, neg, topic, speaker=None)

Creates a Wh-question in the following form:

<Wh-> <rel> <neg> <topic> ?

For example, “Where is the closest shop?”

pydialogue.language.sentences.be(topic, rel, neg, comment, speaker=None)

Create a Sentence for the verb to be in the following form:

<topic> <rel> <neg> <comment>

An example is, “The rug’s color is blue.”

pydialogue.language.sentences.cont(sentences, speaker=None)

Concatenates multiple independent sentences (of type Sentence) into a single compound sentence.

Parameters:

• sentences (list) – The list of sentences.

• speaker (Entity) – The agent who utters the sentence.

Returns:

new_sent – The sentence that contains two or more sentences.

Return type:

Sentence

pydialogue.language.sentences.cont_and(sentences, connector='and', speaker=None)

Concatenates multiple independent sentences (of type Sentence) with a connector in a single compound sentence.

Parameters:

• sentences (list) – The list of sentences.

• speaker (Entity, optional) – The agent who utters the sentence.

• connector (str) – The connector that appears between the sentences.

Returns:

new_sent – The concatenated sentence.

Return type:

Sentence

pydialogue.language.sentences.drop(player=(None, None), mod=(None, None), neg=(None, None), rel=(None, None), entity=(None, None), prepos_location=(None, None), speaker=None)

Creates a Sentence for the verb drop in the following form:

<player> <mod> <neg> <rel> <entity> <prepos_location>

An example is: The big person should drop the apple on the table.

pydialogue.language.sentences.get(player=(None, None), mod=(None, None), neg=(None, None), rel=(None, None), entity=(None, None), prepos_location=(None, None), speaker=None)

Creates a Sentence for the verb get in the following form:

<user> <mod> <neg> <rel> <entity> <prepos_location>

An example is “Hans can not get the small ball in the toy’s container.”

pydialogue.language.sentences.go(player=(None, None), mod=(None, None), neg=(None, None), rel=(None, None), direction=(None, None), source_location=(None, None), target_location=(None, None), speaker=None)

Creates a Sentence for the verb go in the following form:

<player> <mod> <neg> <rel> <direction> <source_location> <target_location>

An example is, “Coco goes north from the porch path to the living room.”

pydialogue.language.sentences.have(entity=(None, None), rel=(None, None), neg=(None, None), possession=(None, None), prepos_location=(None, None), speaker=None)

Creates a Sentence for the verb have in the following form:

<entity> <neg> <rel> <possession> <prepos_location>

An example is: Hans Mustermann has the rug.

pydialogue.language.sentences.issue(issuer, mod, neg, rel, thing_issued, speaker=None)

Creates a Sentence for the verb issue in the following form:

<issuer> <mod> <neg> <rel> <thing_issued>

An example is, “Heidi issued an unrecognizable command.”

pydialogue.language.sentences.know(knower, neg, rel, fact_known, speaker=None)

Creates a Sentence for the verb know in the following form:

<knower> <rel> <neg> <fact_known>

An example is, “He knows not whether the toys container is closed.”

pydialogue.language.sentences.look(looker=(None, None), mod=(None, None), neg=(None, None), rel=(None, None), thing_looked=(None, None), speaker=None)

Creates a Sentence for the verb look in the following form:

<looker> <mod> <neg> <rel> <thing_looked> <item_location>

An example is “Jim looks in the bathroom.”

pydialogue.language.sentences.path_reveal(source_location, target_location, neg, rel, speaker=None)

Creates a Sentence in the following form:

Path from <source_location> to <target_location> <is> <neg> <rel>.

An example is “The path from the barn to the living room is not revealed.”

pydialogue.language.sentences.permit(action_allowed=(None, None), neg=(None, None), rel=(None, None), allower=(None, None), speaker=None)

Creates a Sentence for the verb permit in the following form:

<action_allowed> is <neg> <rel> <allower>

An example is “Getting players is not permitted.”

pydialogue.language.sentences.qwant(wanter, neg, rel, thing_wanted, speaker=None)

Creates a question with the verb want in the following form:

<wanter> <neg> <rel> <thing_wanted> ?

For example: Do you want to get a small latte?

pydialogue.language.sentences.reduce_say(say_sent, user, agent, speaker)

Reduces a complex-compound say(…) sentence into multiple complex sentences. For example, the following sentence: “Max says to Andy: go to the kitchen and get the flour bag” gets reduced to two sentences: “Max says to Andy: go to the kitchen”, “Max says to Andy: get the flour bag.”

Parameters:

• say_sent (Sentence) – The list of sentences.

• user (Entity) – The player issuing the say sentence. It’s Max in the example above.

• agent (list or None) – The player that is addressed. It’s [‘to’, andy] in the example above. This parameter is optional.

• speaker (Entity) – The player that utters the sentence.

Returns:

new_sent – The list of complex sentences that have type Sentence.

Return type:

list

pydialogue.language.sentences.reveal(revealer, neg, rel, truth_cond, speaker=None)

Creates a Sentence in the following form:

<truth_cond> is <neg> <rel> <revealer>

An example is “The living room’s location is not revealed.”

pydialogue.language.sentences.say(user=(None, None), neg=(None, None), rel=(None, None), statement=(None, None), agent=(None, None), speaker=None)

Creates a Sentence for the verb say in the following form:

<user> (neg) <say> <agent>: <statement>

An example is “Hans says to Andy: drop the carrot on the table”

pydialogue.language.sentences.see(player, neg, rel, item, item_location=(None, None), speaker=None)

Creates a Sentence for the verb see in the following form:

<player> <neg> <rel> <item> <item_location>

An example is “Hannah sees Andy in the kitchen.”

pydialogue.language.sentences.tries(entity_trying, mod, neg, rel, thing_tried, speaker=None)

Creates a Sentence for the verb try in the following form:

<entity_trying> <mod> <neg> <rel> <thing_tried>

An example is, “Coco tries going north.”

pydialogue.language.sentences.want(wanter, neg, rel, thing_wanted, speaker=None)

Creates a Sentence for the verb want in the following form:

<wanter> <neg> <rel> <thing_wanted>

An example is, “Hannah wants the red toy.”

pydialogue.language.words module

This module provides a function that creates a specific word.

pydialogue.language.words.create_word_property(item, property_name)

Converts the item.properties[property_name] into a language component (lc.Phrase, lc.Word) or in a list of lc.Word-s.

pydialogue.language.words.create_words_from_string(string_value)

Converts the string into a list of lc.Word-s

Module contents