Package: alexafsm
alexafsmFinite-state machine library for building complex Alexa
conversations.Free software: Apache Software License 2.0.Dialog agents need to keep track of the various pieces of information to
make decisions how to respond to a given user input. This is referred to
as context, session, or state tracking. As the dialog complexity
increases, this state-tracking logic becomes harder to write, debug, and
maintain. This library takes the finite-state machine design approach to
address this complexity. Developers using this library can model dialog
agents with first-class concepts such as states, attributes, transition,
and actions. Visualization and other tools are also provided to help
understand and debug complex FSM conversations.Also check out ourblog
post.FeaturesFSM-based library for building Alexa skills with complex dialog state
tracking.Tools to validate, visualize, and print the FSM graph.Support analytics withVoiceLabs.Can be paired with any Python server library (Flask, CherryPy, etc.)Written in Python 3.6 (primarily for type annotation and string
interpolation).Getting StartedInstall fromPyPi:pip install alexafsmConsult theAlexa skill
searchskill in thetestsdirectory for details of how to write analexafsmskill. An Alexa skill is composed of the following three
classes:SessionAttributes,States, andPolicy.SessionAttributesSessionAttributesis a class that holds session attributes
(alexa_request['session']['attributes']) and any information we need
to keep track of dialog state. * The core attributes areintent,slots, andstate. *intentandslotsmap directly to
Alexa’s concepts. *slotsshould be of typeSlots, which in
turn is defined as a named tuple, one field for each slot type. In the
skill search example,Slots =namedtuple('Slots',['query', 'nth']).
This named tuple class should be specified in the class definition asslots_cls = Slots. *stateholds the name of the current state
in the state machine. * Each Alexa skill can contain arbitrary number
of additional attributes. If an attribute is not meant to be sent back
to Alexa server (e.g. so as to reduce the payload size), it should be
added tonot_sent_fields. In the skill search example,searchedandfirst_timeare not sent to Alexa server.See the implementation of skill search skill’s`SessionAttributes<https://github.com/allenai/alexafsm/blob/master/tests/skillsearch/session_attributes.py>`__StatesStatesis a class that specifies most of the FSM and its behavior.
It holds a reference to aSessionAttributesobject, the type of
which is specified by overriding thesession_attributes_clsclass
attribute. The FSM is specified by a list of parameter-less methods.
Consider the following method:@with_transitions({'trigger':NEW_SEARCH,'source':'*','prepare':'m_search','conditions':'m_has_result_and_query'},{'trigger':NTH_SKILL,'source':'*','conditions':'m_has_nth','after':'m_set_nth'},{'trigger':PREVIOUS_SKILL,'source':'*','conditions':'m_has_previous','after':'m_set_previous'},{'trigger':NEXT_SKILL,'source':'*','conditions':'m_has_next','after':'m_set_next'},{'trigger':amazon_intent.NO,'source':'has_result','conditions':'m_has_next','after':'m_set_next'})defhas_result(self)->response.Response:"""Offer a preview of a skill"""attributes=self.attributesquery=attributes.queryskill=attributes.skillasked_for_speech=''ifattributes.first_time_presenting_results:asked_for_speech=_you_asked_for(query)ifattributes.number_of_hits==1:skill_position_speech='The only skill I found is'else:skill_position_speech=f'The{ENGLISH_NUMBERS[attributes.skill_cursor]}skill is'ifattributes.first_time_presenting_results:ifattributes.number_of_hits>6:num_hits=f'Here are the top{MAX_SKILLS}results.'else:num_hits=f'I found{len(attributes.skills)}skills.'skill_position_speech=f'{num_hits}{skill_position_speech}'returnresponse.Response(speech=f"{asked_for_speech}"f"{skill_position_speech}{_get_verbal_skill(skill)}."f"{HEAR_MORE}",card=f"Search for{query}",card_content=f"""
        Top result:{skill.name}{_get_highlights(skill)}""",reprompt=DEFAULT_PROMPT)Each method encodes the following:The name of the method is also the name of a state (describing)
in the FSM.The method may be decorated with one or several transitions, usingwith_transitionsdecorators. Transitions can be inbound
(sourceneeds to be specified) or outbound (destneeds to be
specified).Each method returns aResponseobject which is sent to Alexa.Transitions can be specified withprepareandconditionsattributes. Seehttps://github.com/tyarkoni/transitionsfor detailed
documentations. The values of these attributes are parameter-less
methods of thePolicyclass.Thepreparemethods are responsible for “actions” of the FSM such
as querying a database. Theaftermethods are responsible for
updating the state after the transition completes. They are the only
methods responsible for side-effects, e.g. modifying the attributes
of the states. This design facilitates ease of debugging.PolicyPolicyis the class that holds everything together. It contains a
reference to aStatesobject, the type of which is specified by
overriding thestates_clsclass attribute. APolicyobject
initializes itself by constructing a FSM based on theStatestype.Policyclass contains the following key methods:handletakes an Alexa request, parses it, and hands over all
intent requests toexecutemethod.executeupdates the policy’s internal state with the request’s
details (intent, slots, session attributes), then callstriggerto make the state transition. It then looks up the corresponding
response generating methods of theStatesclass to generate a
response for Alexa.initializewill initialize a policy without any request.validateperforms validation of a policy object based onPolicyclass definition and a intent schema json file. It looks
for intents that are not handled, invalid source/dest/prepare
specifications, and unreachable states. The test intest_skillsearch.pyperforms such validation as a test ofalexafsm.The Alexa skill search skill in thetestsdirectory also contains a
Flask-based server that shows how to usePolicyin five lines of
code:@app.route('/',methods=['POST'])defmain():req=flask_request.jsonpolicy=Policy.initialize()returnjson.dumps(policy.handle(req,settings.vi)).encode('utf-8')Other Toolsalexafsmsupports validation, graph visualization, and printing of
the FSM.ValidationSimply initialize aPolicybefore callingvalidate. This
function takes as input the path to the skill’s Alexa intent schema json
file and performs the following checks:All Alexa intents have corresponding events/triggers in the FSM.All states have either inbound or outbound transitions.All transitions are specified with valid source and destination
states.All conditions and prepare actions are handled with methods in thePolicyclass.Change Detection with Record and PlaybackWhen making code changes that are not supposed to impact a skill’s
dialog logic, we may want a tool to check that the skill’s logic indeed
stay the same. This is done by first recording
(SkillSettings().record= True) one or several sessions, making the
code change, then checking if the changed code still produces the same
set of dialogs (SkillSettings().playback= True). During playback,
calls to databases such as ElasticSearch can be fulfilled from data read
from files generated during the recording. This is done by decorating
the database call withrecordablefunction. Seethe ElasticSearch
callin Skill Search for an example usage.Graph Visualizationalexafsmuses thetransitionslibrary’s API to draw the FSM
graph. For example, the skill search skill’s FSM can be visualized using
thegraph.py.
invoked fromgraph.sh.
The resulting graph is displayed follow:FSM ExampleGraph PrintoutFor complex graphs, it may be easier to inspect the FSM in text format.
Use theprint_machinemethod to accomplish this. The output for the
skill search skill is below:Machine states:
    bad_navigate, describe_ratings, describing, exiting, has_result, helping, initial, is_that_all, no_query_search, no_result, search_prompt

Events and transitions:

Event: NthSkill
    Source: bad_navigate
        bad_navigate -> bad_navigate, conditions: ['m_has_nth']
        bad_navigate -> has_result, conditions: ['m_has_nth']
    Source: describe_ratings
        describe_ratings -> bad_navigate, conditions: ['m_has_nth']
        describe_ratings -> has_result, conditions: ['m_has_nth']
    Source: describing
        describing -> bad_navigate, conditions: ['m_has_nth']
        describing -> has_result, conditions: ['m_has_nth']
    Source: exiting
        exiting -> bad_navigate, conditions: ['m_has_nth']
        exiting -> has_result, conditions: ['m_has_nth']
    Source: has_result
        has_result -> bad_navigate, conditions: ['m_has_nth']
        has_result -> has_result, conditions: ['m_has_nth']
    Source: helping
        helping -> bad_navigate, conditions: ['m_has_nth']
        helping -> has_result, conditions: ['m_has_nth']
    Source: initial
        initial -> bad_navigate, conditions: ['m_has_nth']
        initial -> has_result, conditions: ['m_has_nth']
    Source: is_that_all
        is_that_all -> bad_navigate, conditions: ['m_has_nth']
        is_that_all -> has_result, conditions: ['m_has_nth']
    Source: no_query_search
        no_query_search -> bad_navigate, conditions: ['m_has_nth']
        no_query_search -> has_result, conditions: ['m_has_nth']
    Source: no_result
        no_result -> bad_navigate, conditions: ['m_has_nth']
        no_result -> has_result, conditions: ['m_has_nth']
    Source: search_prompt
        search_prompt -> bad_navigate, conditions: ['m_has_nth']
        search_prompt -> has_result, conditions: ['m_has_nth']
Event: PreviousSkill
    Source: bad_navigate
        bad_navigate -> bad_navigate, conditions: ['m_has_previous']
        bad_navigate -> has_result, conditions: ['m_has_previous']
    Source: describe_ratings
        describe_ratings -> bad_navigate, conditions: ['m_has_previous']
        describe_ratings -> has_result, conditions: ['m_has_previous']
    Source: describing
        describing -> bad_navigate, conditions: ['m_has_previous']
        describing -> has_result, conditions: ['m_has_previous']
    Source: exiting
        exiting -> bad_navigate, conditions: ['m_has_previous']
        exiting -> has_result, conditions: ['m_has_previous']
    Source: has_result
        has_result -> bad_navigate, conditions: ['m_has_previous']
        has_result -> has_result, conditions: ['m_has_previous']
    Source: helping
        helping -> bad_navigate, conditions: ['m_has_previous']
        helping -> has_result, conditions: ['m_has_previous']
    Source: initial
        initial -> bad_navigate, conditions: ['m_has_previous']
        initial -> has_result, conditions: ['m_has_previous']
    Source: is_that_all
        is_that_all -> bad_navigate, conditions: ['m_has_previous']
        is_that_all -> has_result, conditions: ['m_has_previous']
    Source: no_query_search
        no_query_search -> bad_navigate, conditions: ['m_has_previous']
        no_query_search -> has_result, conditions: ['m_has_previous']
    Source: no_result
        no_result -> bad_navigate, conditions: ['m_has_previous']
        no_result -> has_result, conditions: ['m_has_previous']
    Source: search_prompt
        search_prompt -> bad_navigate, conditions: ['m_has_previous']
        search_prompt -> has_result, conditions: ['m_has_previous']
Event: NextSkill
    Source: bad_navigate
        bad_navigate -> bad_navigate, conditions: ['m_has_next']
        bad_navigate -> has_result, conditions: ['m_has_next']
    Source: describe_ratings
        describe_ratings -> bad_navigate, conditions: ['m_has_next']
        describe_ratings -> has_result, conditions: ['m_has_next']
    Source: describing
        describing -> bad_navigate, conditions: ['m_has_next']
        describing -> has_result, conditions: ['m_has_next']
    Source: exiting
        exiting -> bad_navigate, conditions: ['m_has_next']
        exiting -> has_result, conditions: ['m_has_next']
    Source: has_result
        has_result -> bad_navigate, conditions: ['m_has_next']
        has_result -> has_result, conditions: ['m_has_next']
    Source: helping
        helping -> bad_navigate, conditions: ['m_has_next']
        helping -> has_result, conditions: ['m_has_next']
    Source: initial
        initial -> bad_navigate, conditions: ['m_has_next']
        initial -> has_result, conditions: ['m_has_next']
    Source: is_that_all
        is_that_all -> bad_navigate, conditions: ['m_has_next']
        is_that_all -> has_result, conditions: ['m_has_next']
    Source: no_query_search
        no_query_search -> bad_navigate, conditions: ['m_has_next']
        no_query_search -> has_result, conditions: ['m_has_next']
    Source: no_result
        no_result -> bad_navigate, conditions: ['m_has_next']
        no_result -> has_result, conditions: ['m_has_next']
    Source: search_prompt
        search_prompt -> bad_navigate, conditions: ['m_has_next']
        search_prompt -> has_result, conditions: ['m_has_next']
Event: AMAZON.NoIntent
    Source: has_result
        has_result -> bad_navigate, conditions: ['m_has_next']
        has_result -> has_result, conditions: ['m_has_next']
    Source: describe_ratings
        describe_ratings -> is_that_all
    Source: describing
        describing -> search_prompt
    Source: is_that_all
        is_that_all -> search_prompt
Event: DescribeRatings
    Source: bad_navigate
        bad_navigate -> describe_ratings, conditions: ['m_has_result']
    Source: describe_ratings
        describe_ratings -> describe_ratings, conditions: ['m_has_result']
    Source: describing
        describing -> describe_ratings, conditions: ['m_has_result']
    Source: exiting
        exiting -> describe_ratings, conditions: ['m_has_result']
    Source: has_result
        has_result -> describe_ratings, conditions: ['m_has_result']
    Source: helping
        helping -> describe_ratings, conditions: ['m_has_result']
    Source: initial
        initial -> describe_ratings, conditions: ['m_has_result']
    Source: is_that_all
        is_that_all -> describe_ratings, conditions: ['m_has_result']
    Source: no_query_search
        no_query_search -> describe_ratings, conditions: ['m_has_result']
    Source: no_result
        no_result -> describe_ratings, conditions: ['m_has_result']
    Source: search_prompt
        search_prompt -> describe_ratings, conditions: ['m_has_result']
Event: AMAZON.YesIntent
    Source: has_result
        has_result -> describing
    Source: describe_ratings
        describe_ratings -> describing
    Source: describing
        describing -> exiting
    Source: is_that_all
        is_that_all -> exiting
Event: AMAZON.CancelIntent
    Source: no_result
        no_result -> exiting
    Source: search_prompt
        search_prompt -> exiting
    Source: is_that_all
        is_that_all -> exiting
    Source: bad_navigate
        bad_navigate -> exiting
    Source: no_query_search
        no_query_search -> exiting
    Source: describing
        describing -> is_that_all
    Source: has_result
        has_result -> is_that_all
    Source: describe_ratings
        describe_ratings -> is_that_all
    Source: initial
        initial -> search_prompt
    Source: helping
        helping -> search_prompt
Event: AMAZON.StopIntent
    Source: no_result
        no_result -> exiting
    Source: search_prompt
        search_prompt -> exiting
    Source: is_that_all
        is_that_all -> exiting
    Source: bad_navigate
        bad_navigate -> exiting
    Source: no_query_search
        no_query_search -> exiting
    Source: describing
        describing -> is_that_all
    Source: has_result
        has_result -> is_that_all
    Source: describe_ratings
        describe_ratings -> is_that_all
    Source: initial
        initial -> search_prompt
    Source: helping
        helping -> search_prompt
Event: NewSearch
    Source: bad_navigate
        bad_navigate -> exiting, conditions: ['m_searching_for_exit']
        bad_navigate -> has_result, prepare: ['m_search'], conditions: ['m_has_result_and_query']
        bad_navigate -> no_query_search, conditions: ['m_no_query_search']
        bad_navigate -> no_result, prepare: ['m_search'], conditions: ['m_no_result']
    Source: describe_ratings
        describe_ratings -> exiting, conditions: ['m_searching_for_exit']
        describe_ratings -> has_result, prepare: ['m_search'], conditions: ['m_has_result_and_query']
        describe_ratings -> no_query_search, conditions: ['m_no_query_search']
        describe_ratings -> no_result, prepare: ['m_search'], conditions: ['m_no_result']
    Source: describing
        describing -> exiting, conditions: ['m_searching_for_exit']
        describing -> has_result, prepare: ['m_search'], conditions: ['m_has_result_and_query']
        describing -> no_query_search, conditions: ['m_no_query_search']
        describing -> no_result, prepare: ['m_search'], conditions: ['m_no_result']
    Source: exiting
        exiting -> exiting, conditions: ['m_searching_for_exit']
        exiting -> has_result, prepare: ['m_search'], conditions: ['m_has_result_and_query']
        exiting -> no_query_search, conditions: ['m_no_query_search']
        exiting -> no_result, prepare: ['m_search'], conditions: ['m_no_result']
    Source: has_result
        has_result -> exiting, conditions: ['m_searching_for_exit']
        has_result -> has_result, prepare: ['m_search'], conditions: ['m_has_result_and_query']
        has_result -> no_query_search, conditions: ['m_no_query_search']
        has_result -> no_result, prepare: ['m_search'], conditions: ['m_no_result']
    Source: helping
        helping -> exiting, conditions: ['m_searching_for_exit']
        helping -> has_result, prepare: ['m_search'], conditions: ['m_has_result_and_query']
        helping -> no_query_search, conditions: ['m_no_query_search']
        helping -> no_result, prepare: ['m_search'], conditions: ['m_no_result']
    Source: initial
        initial -> exiting, conditions: ['m_searching_for_exit']
        initial -> has_result, prepare: ['m_search'], conditions: ['m_has_result_and_query']
        initial -> no_query_search, conditions: ['m_no_query_search']
        initial -> no_result, prepare: ['m_search'], conditions: ['m_no_result']
    Source: is_that_all
        is_that_all -> exiting, conditions: ['m_searching_for_exit']
        is_that_all -> has_result, prepare: ['m_search'], conditions: ['m_has_result_and_query']
        is_that_all -> no_query_search, conditions: ['m_no_query_search']
        is_that_all -> no_result, prepare: ['m_search'], conditions: ['m_no_result']
    Source: no_query_search
        no_query_search -> exiting, conditions: ['m_searching_for_exit']
        no_query_search -> has_result, prepare: ['m_search'], conditions: ['m_has_result_and_query']
        no_query_search -> no_query_search, conditions: ['m_no_query_search']
        no_query_search -> no_result, prepare: ['m_search'], conditions: ['m_no_result']
    Source: no_result
        no_result -> exiting, conditions: ['m_searching_for_exit']
        no_result -> has_result, prepare: ['m_search'], conditions: ['m_has_result_and_query']
        no_result -> no_query_search, conditions: ['m_no_query_search']
        no_result -> no_result, prepare: ['m_search'], conditions: ['m_no_result']
    Source: search_prompt
        search_prompt -> exiting, conditions: ['m_searching_for_exit']
        search_prompt -> has_result, prepare: ['m_search'], conditions: ['m_has_result_and_query']
        search_prompt -> no_query_search, conditions: ['m_no_query_search']
        search_prompt -> no_result, prepare: ['m_search'], conditions: ['m_no_result']
Event: AMAZON.HelpIntent
    Source: bad_navigate
        bad_navigate -> helping
    Source: describe_ratings
        describe_ratings -> helping
    Source: describing
        describing -> helping
    Source: exiting
        exiting -> helping
    Source: has_result
        has_result -> helping
    Source: helping
        helping -> helping
    Source: initial
        initial -> helping
    Source: is_that_all
        is_that_all -> helping
    Source: no_query_search
        no_query_search -> helping
    Source: no_result
        no_result -> helping
    Source: search_prompt
        search_prompt -> helpingHistory0.1.0 (2017-02-23)First release on PyPI.