beam_search.data_structs

Classes

`Action`(name, probability, beam, score)	Describes an Action.
`Beam`(last_action, last_intent, rankings, ...)	Describes a beam.
`Intent`(name, probability, beam, score, outcome)	Describes an Intent.
`Output`(name, probability, beam, score)	Describes an output, which is either an action or intent.
`RolloutBase`()	Abstract "rollout" class to be inherited.

class Action(name: str, probability: float, beam: int, score: float)[source]

Bases: Output

Describes an Action.

class Beam(last_action: Action | None, last_intent: Intent | None, rankings: List[Output], rollout: RolloutBase, scores: List[float], fallbacks: int)[source]

Bases: object

Describes a beam.

Parameters:

last_action (Optional[Action]) -- The last action that occurred. Can be None upon initiation.
last_intent (Optional[Intent]) -- The last intent that occurred. Can be None upon initiation.
rankings (List[Output]) -- The list of actions or intents in the beam.
rollout (RolloutBase) -- Handles retrieving action and intent confidences, updating the state/applicable actions, etc. This stub class should be implemented with functions that reflect your particular chatbot.
scores (List[float]) -- The list of scores in the beam.
fallbacks (int) -- The number of fallbacks that have occurred in the beam so far.

fallbacks: int

last_action: Action | None

last_intent: Intent | None

rankings: List[Output]

rollout: RolloutBase

scores: List[float]

class Intent(name: str, probability: float, beam: int, score: float, outcome: str)[source]

Bases: Output, ABC

Describes an Intent.

Parameters:: outcome (str) -- The outcome chosen from the intent.

_abc_impl = <_abc_data object>

abstract is_fallback(*args, **kwargs) → bool[source]

Determines if the provided intent is a fallback.

Returns:: True if the intent is a fallback, False otherwise.
Return type:: bool

class Output(name: str, probability: float, beam: int, score: float)[source]

Bases: object

Describes an output, which is either an action or intent. Sorts based on cumulative score.

Parameters:

name (str) -- The name of the output.
probability (float) -- The confidence this output occurred.
beam (int) -- The beam that the output initially belonged to, which does not change if the beam order/id becomes shifted. This is because the beam attribute is only important at the point where the output is chosen so we can add the output to that beam's rankings. For example, if an Output from beam 0 is chosen, but this output is the second best option, the reconstructed beam will be beam 1, but the Output's beam id will still be 0, indicating which beam the output originated from at that point.
score (float) -- The cumulative score of the beam up to and including the output.

class RolloutBase[source]

Bases: ABC

Abstract "rollout" class to be inherited. Houses all the functions that calculate action and intent confidences and keep track of + update the current state.

NOTE: You will also need an "applicable_actions" attribute (set of the currently applicable actions).

Parameters:: ABC (class) -- Used to create an abstract class.

_abc_impl = <_abc_data object>

abstract _update_applicable_actions(*args, **kwargs)[source]

Updates which actions are applicable in the current state.

Raise an error if there are no applicable actions and there are still utterances left. Raise a warning if we reach the goal but there are still utterances left.

(Use the in_run attribute of ConversationAlignmentExecutor to do this).

abstract call_outcome_determiner(*args, **kwargs) → List[source]

Calls the outcome determiner of an action.

Returns:: A list of outcomes ranked by confidence.
Return type:: List

abstract check_system_case(*args, **kwargs) → bool[source]

Checks if system action(s) can be run in the current state (see the docstring in core).

Returns:: True if system action(s) can be run in the current state, False otherwise.
Return type:: bool

abstract copy(*args, **kwargs)[source]

Returns an un-aliased copy of the Rollout. This is needed for when we are performing a restructuring of the beams and the Rollouts need to be transferred over. A "deep" copy is necessary to prevent aliasing in the case where multiple beams are expanded from one "previous" beam.

Returns:: A "deep" copy of itself.

abstract get_action_confidences(*args, **kwargs) → Dict[source]

Returns: (all) the action confidences that match an agent utterance. NOTE: Do not just return the k highest actions, because the top k are selected based on overall score, not just the singular confidence.

Returns:

The action confidence map. Return in the format:

{
    ACTION_NAME (str): CONFIDENCE (float),
    # continue for each action
    ...
}
NOTE: Insertion order of dictionary values is maintained as of Python 3.7.

Return type:

Dict

abstract get_intent_confidences(*args, **kwargs) → List[Dict][source]

Returns: (all) the intent confidences that match a user utterance. NOTE: Do not just return the k highest intents, because the top k are selected based on overall score, not just the singular confidence.

Returns:

The intent/confidence map. Return in the format:

[
    {
        "intent": INTENT_NAME (str),
        "outcome": OUTCOME_NAME (str),
        "confidence": CONFIDENCE (float)
    },
    # continue for each intent
    {
        ...
    }
]

Return type:

List[Dict]

abstract get_reached_goal(*args, **kwargs) → bool[source]

Returns if the beam reached the goal.

Returns:: True if the corresponding beam reached the goal, False otherwise.
Return type:: bool

abstract is_message_action(*args, **kwargs)[source]: Returns if the given action is a message action. This is used within update_if_message_action as well as the core algorithm.

abstract update_if_message_action(*args, **kwargs) → Dict | None[source]

Checks if the provided action is a "message" action, meaning it only has one outcome. If that's the case, the outcome must be automatically executed as it won't take (or need) user input to be determined. This execution is already handled within the beam search algorithm; this function just needs to return the associated intent. So:

Check if the action is a "message" action (with :py:func:`is_message_action

<beam_search.beam_srch_data_structs.RolloutBase.is_message_action>`.)

If it is, update the state with the single outcome and return a single intent in the form
{
    "intent": INTENT_NAME (str),
    "outcome": OUTCOME_NAME (str),
    "confidence": CONFIDENCE (float)
}

Otherwise, just return None.

Returns:: The associated intent if the action is a "message" action; None otherwise.
Return type:: Optional[Dict]

abstract update_state(*args, **kwargs)[source]: Update the state (including applicable actions, so _update_applicable_actions should be called here).