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

Functions
Expand a plan node using the subplan headed by another node. |
|
Get the first plan node in a linked list of plan nodes. |
|
Get the last plan node in a linked list of plan nodes. |
|
Create a plan structure from a list of eventualities, assumed to occur sequentially. |
|
Insert a new plan directly before a given plan node in the linked list. |
|
Merge a sequence of plan nodes (bounded between a given start and end node) into a given subplan node. |
|
Visualize a plan as a graph using graphviz dot. |
Classes
A node in the doubly linked list that represents the system's plan. |
|
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.
- 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.
- 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_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.
- status(before=3, after=5, schemas=False)[source]
Format the plan structure as a status string showing the current, past, and future surface steps.
- serialize_subtree(schemas=False)[source]
Format a string representing the subtree of the plan structure reachable from this node.
- serialize_from_roots(schemas=False)[source]
Format a string representing the subtrees of the plan structure reachable from each root step.
- 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:
- 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.
- event
The eventuality corresponding to this step.
- Type:
- supersteps
A list of more abstract plan steps which this step (partially) realizes.
- obligations
A list of dialogue obligations associated with this plan step.
- Type:
- schemas
A list of schemas that this expected/intended step arises from (if any).
- 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.
- 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:
- 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.
- 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.
- 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:
- Returns:
The new subplan node that replaced the merged sequence.
- Return type:
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:
- Returns:
The first node in the created plan structure.
- Return type:
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.