eta.plan

Classes and methods for creating and modifying dialogue plan structures.

A plan structure consists of a doubly linked list of plan nodes, interpreted as sequentially ordered steps in the system’s plan. Each step contains the expected or intended event corresponding to that node.

Additionally, plan steps may be related to other plan steps in a tree structure, such that each plan step has a list of substeps (more concrete steps that together constitute an abstract step), as well as a list of supersteps (more abstract steps that a step partially constitutes).

The process of planning dialogue, then, consists of iteratively expanding abstract steps to create a “frontier” of concrete plan steps, which become plan nodes (replacing the plan node that previously held the abstract step).

Similarly, executing a plan consists of advancing the pointer to the currently due plan node within the linked list of plan nodes.

TODO: short writeup explaining figure

../_images/plan.png

Functions

expand_plan_node

Expand a plan node using the subplan headed by another node.

get_first_plan_node

Get the first plan node in a linked list of plan nodes.

get_last_plan_node

Get the last plan node in a linked list of plan nodes.

init_plan_from_eventualities

Create a plan structure from a list of eventualities, assumed to occur sequentially.

insert_before_plan_node

Insert a new plan directly before a given plan node in the linked list.

merge_plan_nodes

Merge a sequence of plan nodes (bounded between a given start and end node) into a given subplan node.

visualize_plan

Visualize a plan as a graph using graphviz dot.

Classes

PlanNode

A node in the doubly linked list that represents the system's plan.

PlanStep

A plan step containing an eventuality, related to other plan steps through a tree structure.

class PlanNode(step)[source]

Bases: object

A node in the doubly linked list that represents the system’s plan.

Parameters:

step (PlanStep) – The plan step contained within this node.

step

The plan step contained within this node.

Type:

PlanStep

prev

The next plan node in the linked list.

Type:

PlanNode

next

The previous plan node in the linked list.

Type:

PlanNode

add_superstep_to_subplan(node)[source]

Add the step of a given plan node as a superstep of each node within the subplan headed by this node.

Parameters:

node (PlanNode) – The node whose step should be added as a superstep.

add_supersteps(start_node, end_node)[source]

Given a subplan bounded between a given start and end node, add each as a superstep of this node.

Parameters:
  • start_node (PlanNode) – The beginning of the subplan whose steps should be added as a superstep.

  • end_node (PlanNode) – The end of the subplan whose steps should be added as a superstep.

add_schema_to_subplan(schema)[source]

Add the given schema to each plan step in the subplan headed by this node.

Parameters:

schema (Schema) – The schema object to add to the schema lists for each plan step.

get_schemas()[source]

Get all schemas of this plan.

get_all_roots()[source]

Get all root plan steps (i.e., the most abstract steps) reachable from the current plan.

bind(var, val)[source]

Bind the given variable symbol to the given value throughout the entire plan structure.

unbind(var)[source]

Unbind the given variable symbol throughout the entire plan structure.

status(before=3, after=5, schemas=False)[source]

Format the plan structure as a status string showing the current, past, and future surface steps.

Parameters:
  • before (int, default=3) – The number of past surface steps to show.

  • after (int, default=5) – The number of future surface steps to show.

  • schemas (bool, default=False) – Whether to also display schema predicates for each step.

Return type:

str

serialize_subtree(schemas=False)[source]

Format a string representing the subtree of the plan structure reachable from this node.

Parameters:

schemas (bool, default=False) – Whether to also display schema predicates for each step.

Return type:

str

serialize_from_roots(schemas=False)[source]

Format a string representing the subtrees of the plan structure reachable from each root step.

Parameters:

schemas (bool, default=False) – Whether to also display schema predicates for each step.

Return type:

str

to_graph(before=3, after=5, schemas=False)[source]

Convert a plan structure to a standard graph object, i.e., a list of vertices and edges.

Parameters:
  • before (int, default=3) – The number of past surface steps to include in the graph.

  • after (int, default=5) – The number of future surface steps to include in the graph.

  • schemas (bool, default=False) – Whether to also display schema predicates in the labels for each step.

Returns:

  • nodes (list[tuple[str, str]]) – A list of vertices/nodes in the resulting graph, where each node is an (<id>, <label>) tuple.

  • edges (list[tuple[str, str]]) – A list of edges in the resulting graph, where each edge is an (<id1>, <id2>) tuple.

class PlanStep(event=None)[source]

Bases: object

A plan step containing an eventuality, related to other plan steps through a tree structure.

Parameters:

event (Eventuality) – The eventuality corresponding to this step.

id

A unique ID for this step.

Type:

str

event

The eventuality corresponding to this step.

Type:

Eventuality

substeps

A list of more concrete plan steps that together realize this step.

Type:

list[PlanStep]

supersteps

A list of more abstract plan steps which this step (partially) realizes.

Type:

list[PlanStep]

obligations

A list of dialogue obligations associated with this plan step.

Type:

list[Eventuality]

schemas

A list of schemas that this expected/intended step arises from (if any).

Type:

list[Schema]

get_obligations()[source]

Get any dialogue obligations associated with a particular step in the plan.

Notes

TODO: this is currently a bit of a hack, in that it involves looking at the superstep as well if no obligations are found. This is because say-to.v actions may need to access the parent paraphrase-to.v actions in order to inherit relevant obligations of the latter. It may be possible to instead modify the plan expansion method so that obligations are inherited upon expansion.

add_superstep(superstep)[source]

Add bidirectional subplan/superplan links between this step and a given superstep.

The schemas of the superstep also become the schemas associated with this step, but only in the case where this step doesn’t already have associated schemas (e.g., if it was created from an episode list in expanding an action).

Parameters:

superstep (PlanStep) – The superstep to add to this step.

Notes

TODO: it’s not clear whether the above is the sensible behavior, or if instead we should always append the schemas of the superstep to this step.

bind(var, val)[source]

Bind the given variable symbol to the given value throughout the entire plan step tree (and associated schemas).

unbind(var)[source]

Unbind the given variable symbol throughout the entire plan step tree (and associated schemas).

serialize(reverse=False, schemas=False)[source]

Format a string representing a serialized version of the subtree rooted at this step.

This is generated using a DFS, maintaining a record of recurring plan steps so that numerical references can be inserted in place of nodes that appear more than once in the tree.

Parameters:
  • reverse (bool, default=False) – If given as True, print the subtree “above” this step rather than below.

  • schemas (bool, default=False) – Whether to also display schema predicates for each step.

Return type:

str

format(schemas=False)[source]

Format a string representing this plan step as an S-expression.

Parameters:

schemas (bool, default=False) – Whether to also display schema predicates for each step.

Returns:

The step formatted as one of the following S-expression string representations: - ((<ep-name> <wff>) <certainty>) - ((<ep-name> <wff>) <certainty>) (:schemas <schema-preds>)

Return type:

str

get_first_plan_node(plan_node)[source]

Get the first plan node in a linked list of plan nodes.

Parameters:

plan_node (PlanNode) – An arbitrary node within the linked list of plan nodes.

Returns:

The first node in the linked list.

Return type:

PlanNode

get_last_plan_node(plan_node)[source]

Get the last plan node in a linked list of plan nodes.

Parameters:

plan_node (PlanNode) – An arbitrary node within the linked list of plan nodes.

Returns:

The last node in the linked list.

Return type:

PlanNode

expand_plan_node(plan_node, subplan_node_start)[source]

Expand a plan node using the subplan headed by another node.

The subplan is inserted into the plan in place of the given plan node, which is done by adding the plan node as a superstep of each step in the subplan, and then modifying the pointers of the linked list so that the step before the plan node points to the first node in the subplan, and the step after the plan node points to the last node in the subplan.

Parameters:
  • plan_node (PlanNode) – The node to expand.

  • subplan_node_start (PlanNode) – The first node in the subplan to replace plan_node with.

Returns:

The first node in the given subplan.

Return type:

PlanNode

insert_before_plan_node(plan_node, new_plan_node_start)[source]

Insert a new plan directly before a given plan node in the linked list.

Parameters:
  • plan_node (PlanNode) – The node that the new plan should precede.

  • new_plan_node_start (PlanNode) – The first node in the new plan to insert before plan_node.

Returns:

The first node in the new plan.

Return type:

PlanNode

merge_plan_nodes(plan_node_start, plan_node_end, new_plan_node)[source]

Merge a sequence of plan nodes (bounded between a given start and end node) into a given subplan node.

Parameters:
  • plan_node_start (PlanNode) – The first node in the plan sequence to merge.

  • plan_node_end (PlanNode) – The last node in the plan sequence to merge.

  • new_plan_node (PlanNode) – The new subplan node that should replace the merged sequence.

Returns:

The new subplan node that replaced the merged sequence.

Return type:

PlanNode

Notes

TODO: this may need to be extended to deal with cases where the plan nodes to merge are discontiguous in the plan.

init_plan_from_eventualities(eventualities, schema=None)[source]

Create a plan structure from a list of eventualities, assumed to occur sequentially.

Parameters:
  • eventualities (list[Eventualities]) – The list of eventualities to use to create a plan.

  • schema (Schema, optional) – If a schema is provided, it will be added to the created plan steps and used to inherit obligations, etc.

Returns:

The first node in the created plan structure.

Return type:

PlanNode

Notes

TODO: we might, in the future, allow for episode-relations in the schema to provide initial constraints over plan construction here.

visualize_plan(plan_node, before=3, after=5, schemas=False, vert=False, dir='io/')[source]

Visualize a plan as a graph using graphviz dot.

Parameters:
  • before (int, default=3) – The number of past surface steps to include in the graph.

  • after (int, default=5) – The number of future surface steps to include in the graph.

  • schemas (bool, default=False) – Whether to also display schema predicates in the labels for each step.

  • vert (bool, default=False) – Whether to rotate the direction of the graph to left-right.

  • dir (str, default='io/') – The directory to store the generated graph image.

Notes

TODO: it may be better to move this function elsewhere in order to have a cleaner dependency structure.