Conversing

The conversing domain use the Understanding and Handling domains to trigger python actions from parsed intents and maintain a conversation state.

Agent

An agent represent the interface between the user and loaded skills. It maintain the conversation state and use an underlying interpreter to understand the user.

The agent is the entry point which will take raw user inputs with its parse method and call loaded handlers as needed.

Entry point

Agent.parse(msg: str, **meta) → None

Parse a raw message.

The interpreter will be used to determine which intent(s) has been formulated by the user and the state machine will move to the appropriate state calling the right skill handler.

It will also handle some specific intents such as the cancel one and ask states.

Parameters:
  • msg (str) – Raw message to parse
  • meta (dict) – Optional metadata to add to the request object

Note

More information on Meta.

When an intent has been found, it will try to find an handler for this specific intent and call it. It will then manage the conversation, handle cancel and fallback intents and communicate back to the user using its internal Client.

From a skill

From a skill perspective, here are the method you will use.

Agent.answer(text: str, cards: Union[pytlas.handling.card.Card, List[pytlas.handling.card.Card]] = None, **meta) → None

Answer something to the user.

Parameters:
  • text (str, list) – Text to show to the user
  • cards (list, Card) – List of Card to show if any
  • meta (dict) – Any additional data to pass to the handler
Agent.ask(slot: str, text: Union[str, List[str]], choices: List[str] = None, **meta) → None

Ask something to the user.

Parameters:
  • slot (str) – Name of the slot asked for
  • text (str, list) – Text to show to the user
  • choices (list) – List of available choices
  • meta (dict) – Any additional data to pass to the handler
Agent.done(require_input=False) → None

Done should be called by skills when they are done with their stuff. It enables threaded scenarii. When asking something to the user, you should not call this method since ask end the skill immediately.

Parameters:require_input (bool) – True if additional informations are needed (mostly use to trigger client input)
Agent.context(context_name: str) → None

Switch the agent to the given context name. It will populates the list of reachable scopes so the interpreter will only parse intents defined in this scope.

Parameters:context_name (str) – Name of the context to switch to (None represents the root one)

Client

A client is a thin layer used by an agent to communicate with the user. It can be anything such as a tiny CLI (as the one provided), a WebSocket server or a connected speaker.

When provided to an agent (using its model property), some specific members will be called by the agent on specific lifecycle events:

on_answer(text, cards, raw_text, **meta)

Called when the skill answer something to the user. cards is a list of pytlas.Card which represents informations that should be presented to the user if possible. Your client should always handle the text property at least.

on_ask(slot, text, choices, raw_text, **meta)

Called when the skill need some user inputs for the given slot. choices if set, represents a list of available choices.

on_thinking()

Called when the agent has called a skill which is handling the request.

on_done(require_input)

Called when a skill has done its work and the agent is going back to the asleep state.

on_context(context_name)

Called when the agent context has changed.