cognition.reasoning.planning¶

Planning support

Attributes¶

`PathCost`	Cost of a plan action (can be whole numbers or decimal)
`Succession`	Given a planning state, produces (state', action, cost) triple(s)

Classes¶

`FrontierNode`	Item on the planning frontier
`FrontierManager`	Data structure to manage the planning frontier
`Stack`	DFS frontier
`Queue`	BFS frontier
`PriorityQueue`	UCS frontier, or A* if given an admissible heuristic
`SearchState`	Internal representation for search-based planning
`SearchPlanner`	A planner that iteratively produces an action
`SearchPlannerStaticOption`	A transition applicable to many states
`SearchPlannerDynamicOption`	A pattern-driven class

Functions¶

`static_opts_succession`(*options)	Succession function from static options
`dynamic_opts_succession`(*option_types)	Succession function from dynamic options

Module Contents¶

type cognition.reasoning.planning.PathCost = int | float¶: Cost of a plan action (can be whole numbers or decimal)

class cognition.reasoning.planning.FrontierNode[PS, PA]¶

Item on the planning frontier

state: PS¶: state that would result

path: collections.abc.Sequence[PA]¶: path of actions to achieve the state

path_cost: PathCost¶: cost of the path to achieve the state

class cognition.reasoning.planning.FrontierManager[PS, PA]¶

Bases: abc.ABC

Data structure to manage the planning frontier

property empty: bool¶

Abstractmethod:
Returns:: True if there are no more items on the frontier
Return type:: bool

abstractmethod add(node)¶

Parameters:: node (FrontierNode[PS, PA]) – item to add to the frontier
Return type:: None

abstractmethod remove()¶

Returns:: the next frontier item
Return type:: FrontierNode[PS, PA]

abstractmethod __str__()¶

Return type:: str

class cognition.reasoning.planning.Stack[PS, PA]¶

Bases: FrontierManager[PS, PA]

DFS frontier

__str__()¶

Return type:: str

property empty: bool¶

Returns:: True if there are no more items on the frontier
Return type:: bool

add(node)¶

Parameters:: node (FrontierNode[PS, PA]) – item to add to the frontier
Return type:: None

remove()¶

Returns:: the next frontier item
Return type:: FrontierNode[PS, PA]

class cognition.reasoning.planning.Queue[PS, PA]¶

Bases: FrontierManager[PS, PA]

BFS frontier

__str__()¶

Return type:: str

property empty: bool¶

Returns:: True if there are no more items on the frontier
Return type:: bool

add(node)¶

Parameters:: node (FrontierNode[PS, PA]) – item to add to the frontier
Return type:: None

remove()¶

Returns:: the next frontier item
Return type:: FrontierNode[PS, PA]

class cognition.reasoning.planning.PriorityQueue[PS, PA](heuristic=None)¶

Bases: FrontierManager[PS, PA]

UCS frontier, or A* if given an admissible heuristic

Parameters:: heuristic (cognition.util.functypes.Function[PS, PathCost] | None) – if supplied, provides an estimate of remaining cost

__str__()¶

Return type:: str

property empty: bool¶

Returns:: True if there are no more items on the frontier
Return type:: bool

add(node)¶

Parameters:: node (FrontierNode[PS, PA]) – item to add to the frontier
Return type:: None

remove()¶

Returns:: the next frontier item
Return type:: FrontierNode[PS, PA]

type cognition.reasoning.planning.Succession = Function[S, Iterable[tuple[S, A, PathCost]]]¶: Given a planning state, produces (state’, action, cost) triple(s)

class cognition.reasoning.planning.SearchState[PS: collections.abc.Hashable, PA]¶

Internal representation for search-based planning

explored: set[PS]¶: states already explored

frontier: FrontierManager[PS, PA]¶: states to be explored

done: bool¶: True if done searching

final_state: PS | None¶: final state, or None if failure

action_path: collections.abc.Sequence[PA] | None¶: sequence of actions to the final state, or None if failure

path_cost: PathCost | None¶: cost of actions to the final state, or None if failure

failure()¶

Frontier has been exhausted

Return type:: None

success(node)¶

Goal state found

Parameters:: node (FrontierNode[PS, PA]) – identified goal state
Return type:: None

__str__()¶

Return type:: str

class cognition.reasoning.planning.SearchPlanner[PS: collections.abc.Hashable, PA](initial_state, is_goal, successors, frontier_factory=PriorityQueue)¶

A planner that iteratively produces an action plan by searching the space of states produced via a succession function starting from an initial state until the goal predicate is satisfied (or all possible options have been exhausted).

Parameters:

initial_state (PS) – starting node
is_goal (cognition.util.functypes.Predicate[PS]) – goal predicate
successors (Succession[PS, PA]) – function to produce node transitions
frontier_factory (cognition.util.functypes.Supplier[FrontierManager[PS, PA]]) – function to prioritize frontier nodes

property still_searching: bool¶

Indicates if the planner still has options to explore.

Returns:: True if the planner has not concluded search
Return type:: bool

run(max_steps=None)¶

Attempts to search for a solution.

Parameters:: max_steps (int | None) – if supplied, maximum number of planner steps to expend before returning
Returns:: this planner (for chaining)
Return type:: Self

property plan_found: bool¶

Indicates if a plan was found.

Returns:: True if the planner was successful
Return type:: bool

property plan: collections.abc.Sequence[PA]¶

The found plan

Raises:: RuntimeError – plan not available
Returns:: sequence of actions to the final state
Return type:: collections.abc.Sequence[PA]

property plan_cost: PathCost¶

Cost of the found plan

Raises:: RuntimeError – plan not available
Returns:: cost of path actions
Return type:: PathCost

property states_explored: int¶

Number of states explored thus far during planning (roughly correlating with effort)

Returns:: number of states explored
Return type:: int

class cognition.reasoning.planning.SearchPlannerStaticOption[PS, PA](action)¶

Bases: abc.ABC

A transition applicable to many states

Parameters:: action (PA) – search action that might be applicable in multiple states

property action: PA¶

Returns:: associated action
Return type:: PA

abstractmethod is_available(state)¶

State-gating predicate

Parameters:: state (PS) – state to consider
Returns:: True if this search action applies
Return type:: bool

abstractmethod then(state)¶

Produces the result of applying this search action to a supplied state

Parameters:: state (PS) – starting state
Returns:: resulting state and cost from applying the search action
Return type:: tuple[PS, PathCost]

class cognition.reasoning.planning.SearchPlannerDynamicOption[PS, PA](action)¶

Bases: abc.ABC

A pattern-driven class of transitions

Parameters:: action (PA) – search action to be performed

property action: PA¶

Returns:: associated action
Return type:: PA

classmethod when(state)¶

Abstractmethod:
Parameters:: state (PS)
Return type:: collections.abc.Iterable[Self]

Identifies planning action(s) that do apply in the supplied state

Parameters:: state (PS) – state to consider
Returns:: instance(s) that apply
Return type:: collections.abc.Iterable[Self]

abstractmethod then(state)¶

Produces the result of applying this search action to a supplied state

Parameters:: state (PS) – starting state
Returns:: resulting state and cost from applying the search action
Return type:: tuple[PS, PathCost]

cognition.reasoning.planning.static_opts_succession[PS, PA](*options)¶

Succession function from static options

Parameters:: options (SearchPlannerStaticOption[PS, PA]) – globally available transitions
Returns:: resulting succession function for any search state
Return type:: Succession[PS, PA]

cognition.reasoning.planning.dynamic_opts_succession[PS, PA](*option_types)¶

Succession function from dynamic options

Parameters:

options – globally available transition types
option_types (type[SearchPlannerDynamicOption[PS, PA]])

Returns:

resulting succession function for any search state

Return type:

Succession[PS, PA]