cognition.decision.dp¶

Decision process (with batteries included)

Attributes¶

`OPERATOR_SELF_PARAM`	Default `NamedObject` parameter key to access source operator
`TERMINAL_ACTION_ATTR`	Attribute name to trigger termination for a selected action

Classes¶

`Rank`	Example 3-level rankings of actions
`NamedObject`	An object that has name/params annotations
`OperatorGenerator`	A pattern for generating state-specific action(s)
`Operator`	A predicate gating a single action
`Elaborable`	Defines a state that supplies an
`DecisionProcess`	Decision process implementation with batteries included

Functions¶

`args_added`(dp, **info)	Provides io.a values temporarily
`create_elaborator`([name])	Elaborator generator given association between keywords and value-producing functions
`format_name_params`(name, **kwargs)	Naming convention for a combo of name + optional params
`create_named_action`(name, f, **kwargs)	Annotates an action via `str()` and attributes
`add_generator`(dp, gen_type, extra[, self_param])	Instantiates the generator within a decision process
`add_operator`(dp, op[, self_param])	Instantiates the operator within a decision process
`uniform_evaluator`(r[, p, name])	Applies a supplied rank to all potential actions that satisfy a predicate
`sorting_evaluator`(sorting_key[, p, rank_start, name])	Associates rankings based upon relative sorting order over actions
`operator_sorting_key`([op_param])	Produces an action sorting key for actions derived from operators

Module Contents¶

cognition.decision.dp.OPERATOR_SELF_PARAM: str = '_op'¶: Default NamedObject parameter key to access source operator

class cognition.decision.dp.Rank¶

Bases: enum.IntEnum

Example 3-level rankings of actions

Initialize self. See help(type(self)) for accurate signature.

HIGH = 1¶: High importance

MEDIUM = 2¶: Medium importance

LOW = 3¶: Low importance

cognition.decision.dp.args_added[S](dp, **info)¶

Provides io.a values temporarily

Parameters:

dp (cognition.decision.core.BaseDecisionProcess[S]) – decision process for which to provide arguments
info (Any) – io.a.key=value

Returns:

supplied dp

Return type:

collections.abc.Generator[cognition.decision.core.BaseDecisionProcess[S]]

cognition.decision.dp.create_elaborator[S](name=None, **kwargs)¶

Elaborator generator given association between keywords and value-producing functions

Parameters:

name (str | None) – optional name
kwargs (cognition.util.functypes.BiFunction[S, cognition.decision.core.IOContainer, Any]) – key=value(state, io)

Returns:

resulting elaborator

Return type:

cognition.decision.core.Elaborator[S]

class cognition.decision.dp.NamedObject¶

Bases: Protocol

An object that has name/params annotations

property name: str¶

Returns:: object name
Return type:: str

property params: collections.abc.Mapping[str, Any]¶

Returns:: optional augmentations in the name
Return type:: collections.abc.Mapping[str, Any]

cognition.decision.dp.format_name_params(name, **kwargs)¶

Naming convention for a combo of name + optional params (ignoring those whose name starts with an underscore)

Parameters:

name (str) – item name
kwargs (Any) – optional params

Returns:

“name” or “name[arg1=val1, arg2=val2, …]”

Return type:

str

cognition.decision.dp.create_named_action[S](name, f, **kwargs)¶

Annotates an action via str() and attributes

Parameters:

name (str) – name to add
f (cognition.decision.core.Action[S]) – original action
kwargs (Any) – arbitrary keyword=value pairs

Returns:

NamedObject + cognition.util.misc.stringify()

Return type:

cognition.decision.core.Action[S]

class cognition.decision.dp.OperatorGenerator[S, X](**kwargs)¶

Bases: _BaseOperator[S]

A pattern for generating state-specific action(s)

Parameters:

name – name for the resulting action [and factory]
kwargs (Any) – optional params for the resulting action

classmethod get_name()¶

Abstractmethod:
Returns:: name for all generated instances
Return type:: str

classmethod generate(state, io, extra)¶

Abstractmethod:

Parameters:

state (S)
io (cognition.decision.core.IOContainer)
extra (X)

Return type:

collections.abc.Iterable[Self]

Produces action(s) that hold in the current state

Parameters:

state (S) – current state
io (cognition.decision.core.IOContainer) – access to input/output
extra (X) – generator-specific data

Returns:

applicable action(s)

Return type:

collections.abc.Iterable[Self]

class cognition.decision.dp.Operator[S](name, **kwargs)¶

Bases: _BaseOperator[S]

A predicate gating a single action

Parameters:

name (str) – name for the resulting action [and factory]
kwargs (Any) – optional params for the resulting action

abstractmethod can_perform(state, io)¶

Does the action hold in the current state?

Parameters:

state (S) – current state
io (cognition.decision.core.IOContainer) – access to input/output

Returns:

True if the action applies in the current state

Return type:

bool

cognition.decision.dp.add_generator[S, X](dp, gen_type, extra, self_param=OPERATOR_SELF_PARAM)¶

Instantiates the generator within a decision process

Parameters:

dp (cognition.decision.core.BaseDecisionProcess[S]) – decision process to be added to
gen_type (type[OperatorGenerator[S, X]]) – source of operators
extra (X) – generator-specific data
self_param (str | None) – if not None, action param -> the produced ops (for purposes of comparison)

Returns:

the produced action factory

Return type:

cognition.decision.core.ActionFactory[S]

cognition.decision.dp.add_operator[S](dp, op, self_param=OPERATOR_SELF_PARAM)¶

Instantiates the operator within a decision process

Parameters:

dp (cognition.decision.core.BaseDecisionProcess[S]) – decision process to be added to
op (Operator[S]) – operator with factory/action info
self_param (str | None) – if not None, action param referring to the op

Returns:

the produced action factory and action

Return type:

tuple[cognition.decision.core.ActionFactory[S], cognition.decision.core.Action[S]]

cognition.decision.dp.uniform_evaluator[S](r, p=lambda _: ..., name=None)¶

Applies a supplied rank to all potential actions that satisfy a predicate

Parameters:

r (cognition.util.misc.ImplementsLessThan) – rank to uniformly apply
p (cognition.util.functypes.Predicate[cognition.decision.core.Action[S]]) – optional predicate to gate potential actions
name (str | None) – optional name of the evaluator

Returns:

resulting evaluator

Return type:

cognition.decision.core.ActionEvaluator[S]

cognition.decision.dp.sorting_evaluator[S](sorting_key, p=lambda _: ..., rank_start=1, name=None)¶

Associates rankings based upon relative sorting order over actions

Parameters:

sorting_key (cognition.util.functypes.TriFunction[cognition.decision.core.Action[S], S, cognition.decision.core.IOContainer, _typeshed.SupportsAllComparisons]) – key function for sort() to order actions
p (cognition.util.functypes.Predicate[cognition.decision.core.Action[S]]) – optional predicate to gate potential actions
rank_start (int) – starting value for produced ranks
name (str | None) – optional name for the evaluator

Returns:

resulting evaluator

Return type:

cognition.decision.core.ActionEvaluator[S]

cognition.decision.dp.operator_sorting_key[S](op_param=OPERATOR_SELF_PARAM)¶

Produces an action sorting key for actions derived from operators

Parameters:: op_param (str) – action param key for operator self-reference
Returns:: key function
Return type:: cognition.util.functypes.TriFunction[cognition.decision.core.Action[S], S, cognition.decision.core.IOContainer, _typeshed.SupportsAllComparisons]

class cognition.decision.dp.Elaborable[S]¶

Bases: Protocol

Defines a state that supplies an elaborator, to be added to a decision process upon initialization

property elaborator: cognition.decision.core.Elaborator[S]¶

Abstractmethod:
Return type:: cognition.decision.core.Elaborator[S]

Provide the state-specific elaborator

Returns:: state-specific elaborator
Return type:: cognition.decision.core.Elaborator[S]

cognition.decision.dp.TERMINAL_ACTION_ATTR: str = 'terminal'¶: Attribute name to trigger termination for a selected action

class cognition.decision.dp.DecisionProcess[S](state_initializer, enable_terminal_check=True)¶

Bases: cognition.decision.core.BaseDecisionProcess[S]

Decision process implementation with batteries included

Parameters:

state_initializer (cognition.util.functypes.Supplier[S]) – produces state initially (and on core.BaseDecisionProcess.reinit())
enable_terminal_check (bool) – if True, a selected named action (create_named_action()) with a TERMINAL_ACTION_ATTR parameter triggers termination during check

args_added(**info)¶

Pass-thru to args_added()

Parameters:: info (Any) – io.a.key=value
Return type:: collections.abc.Generator[cognition.decision.core.BaseDecisionProcess[S]]

add_generator[X](gen_type, extra, self_param=OPERATOR_SELF_PARAM)¶

Pass-thru to add_generator().

Parameters:

gen_type (type[OperatorGenerator[S, X]]) – source of operators
self_param (str | None) – if not None, action param referring to the op
extra (X) – generator-specific data

Returns:

the produced action factory and this decision process (for chaining)

Return type:

tuple[cognition.decision.core.ActionFactory[S], Self]

add_generator_c[X](gen_type, extra, self_param=OPERATOR_SELF_PARAM)¶

Pass-thru to DecisionProcess.add_generator().

Parameters:

gen_type (type[OperatorGenerator[S, X]]) – source of operators
extra (X) – generator-specific data
self_param (str | None) – if not None, action param referring to the op

Returns:

this decision process (for chaining)

Return type:

Self

generator[X](extra, self_param=OPERATOR_SELF_PARAM)¶

Decorator version of add_generator()

Parameters:

extra (X) – generator-specific data
self_param (str | None) – if not None, action param referring to the op

Returns:

parameterized decorator

Return type:

cognition.util.functypes.Function[type[OperatorGenerator[S, X]], type[OperatorGenerator[S, X]]]

add_operator(op, self_param=OPERATOR_SELF_PARAM)¶

Pass-thru to add_operator().

Parameters:

op (Operator[S]) – operator with factory/action info
self_param (str | None) – if not None, action param referring to the op

Returns:

the produced action factory and action, and this decision process (for chaining)

Return type:

tuple[cognition.decision.core.ActionFactory[S], cognition.decision.core.Action[S], Self]

add_operator_c(op, self_param=OPERATOR_SELF_PARAM)¶

Pass-thru to add_operator().

Parameters:

op (Operator[S]) – operator with factory/action info
self_param (str | None) – if not None, action param referring to the op

Returns:

this decision process (for chaining)

Return type:

Self

operator(op_name, self_param=OPERATOR_SELF_PARAM, **kwargs)¶

Decorator version of add_operator() that assumes instantiation takes a positional name and arbitrary keywords

Parameters:

op_name (str) – name to give to the added instance
self_param (str | None) – if not None, action param referring to the op
kwargs (Any) – operator params

Returns:

parameterized named-object decorator

Return type:

cognition.util.functypes.Function[type[Operator[S]], type[Operator[S]]]

__call__(max_cycles=None, suppress_errors=True, **args)¶

Execute the decision process, function-style

Parameters:

max_cycles (int | None) – maximum steps to execute (or None for no limit)
suppress_errors (bool) – if True, does not raise any errors from execution
args (Any) – arguments to supply

Returns:

the final state if the decision process completed without any exceptions; None otherwise

Return type:

S | None