Files
FireIsGood 413891a020 fix: alan-ai format
Styles at the bottom removed
2024-05-16 14:38:40 -07:00

503 lines
8.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: Alan AI
date: 2023-03-03 6:00:00
background: bg-[#4aa181]
tags:
- AI
- AlanAI
- Prompts
- Tips
categories:
- Toolkit
intro:
This cheat sheet covers all major script concepts, client API methods, handlers and other tools to create a multimodal
conversational experience with Alan AI
---
### Legend
- `pattern` — phrase to invoke a voice/text command or a response to be played
- `value` — specified value
- `params` — passed parameters
- `action` — action to be performed
- `output` — data outcome
- `[...]` — optional data or parameters
## Dialog script
### Intents & patterns
Define a voice/text command to play a response
```{.wrap}
intent('pattern'[, 'patternN'], reply('pattern'))
```
Define a voice/text command to play a response or perform an action
```{.wrap}
intent('pattern'[, 'patternN'], p => { action })
```
Define alternatives
```{.wrap}
intent('phrase1|phrase2')
```
Define optional words and phrases
```{.wrap}
intent('pattern (optional phrase|)')
```
### Response functions
Play a response (in case of multiple patterns, a response is picked at random)
```{.wrap}
reply('pattern'[, 'patternN'])
```
Play a response
```{.wrap}
p.play('pattern')
```
Define voice settings for the assistant reply: `accent (en, fr, de, it, ru, es)`, `gender (male/female)`, `voice type`,
`speaking pitch`, `speaking rate`
```{.wrap}
p.play([voice(code, gender, type, pitch, rate), ]'pattern')
```
Define play options: `force:true` (execute if the button is inactive), `activate:true` (activate the button before),
`deactivate:true` (deactivate the button after)
```{.wrap}
p.play('pattern'[, opts(options)])
```
Send a command to the app
```{.wrap}
p.play({command:data})
```
### User-defined slots
Define a static list of values expected in the input
```{.wrap}
$(SLOTNAME value1|value2) => p.SLOTNAME.value
```
Provide labels to classify or identify the slot values
```{.wrap}
$(SLOTNAME value1~label1|value2~label2) => p.SLOTNAME.label
```
Enable fuzzy matching to capture similar variants
```{.wrap}
$(SLOTNAME~ value1|value2) => p.SLOTNAME.value
```
Make a slot optional
```{.wrap}
$(SLOTNAME value1|value2|)
```
Capture several slot values
```{.wrap}
intent('$(SLOTNAME value1|value2) and $(SLOTNAME value1|value2 )') => p.SLOTNAME_ (array), p.SLOTNAME_[0].value, p.SLOTNAME_[1].value
```
### Predefined slots
Capture date values
```{.wrap}
$(DATE) => p.DATE.value, p.DATE.moment, p.DATE.luxon
```
Capture time values
```{.wrap}
$(TIME) => p.TIME.value, p.TIME.moment
```
Capture cardinal numbers
```{.wrap}
$(NUMBER) => p.NUMBER.value, p.NUMBER.number
```
Capture ordinal numbers
```{.wrap}
$(ORDINAL) => p.ORDINAL.value, p.ORDINAL.number
```
Capture locations
```{.wrap}
$(LOC) => p.LOC.value
```
Capture names
```{.wrap}
$(NAME) => p.NAME.value
```
### Dynamic slots
Define a dynamic slot at the project level
```{.wrap}
project.name = {en: "value1|value2|value3"}
$(SLOTNAME p:name) => p.SLOTNAME.value
```
Define a dynamic slot at the dialog session level
```{.wrap}
p.userData.name = {en: "value1|value2|value3"}
$(SLOTNAME u:name) => p.SLOTNAME.value
```
Get data for a dynamic slot with the visual state
```{.wrap}
let name = ["value1|value2|value3"]
p.visual.data = {en: name};
$(SLOTNAME v:name) => p.SLOTNAME.value
```
Define a dynamic slot in a short form
```{.wrap}
project.name = {en: "value1|value2|value3"}
$(p:name) => p.SLOTNAME.value
```
Define labels for dynamic slots: see [User-defined slots](#user-defined-slots).
Enable fuzzy matching for dynamic slots: see [User-defined slots](#user-defined-slots).
Make a dynamic slot optional: see [User-defined slots](#user-defined-slots).
Capture several slot values: see [User-defined slots](#user-defined-slots).
### RegEx slots
Capture digit and/or letter combination
```{.wrap}
const reg = "([A-Za-z]{1}\\s?){6}"
$(SLOTNAME* ${reg}) => p.SLOTNAME.value
```
Capture any user’s input
```{.wrap}
$(SLOTNAME* .+) => p.SLOTNAME.value
```
### Contexts
Define a context
```{.wrap}
let contextName = context(() => { action })
```
Activate a context
```{.wrap}
intent('pattern', p => {..., p.then(contextName)}
```
Pass data to the context
```{.wrap}
p.then(contextName, state: {data:yourData}) => p.state.data
```
Resolve a context
```{.wrap}
p.resolve([data:yourData])
```
Reset a context
```{.wrap}
p.resetContext()
```
Define intents to be matched at any time without switching the current context
```{.wrap}
intent(noctx, 'pattern', ...) or noContext(() => {intent(...)})
```
Play a prompt for an expected input
```{.wrap}
fallback('pattern1'[, 'patternN'])
```
Title a context
```{.wrap}
title('contextName')
```
### Predefined objects
Store static device- and user-specific data passed from the client app
```{.wrap}
authData.data => p.authData.data
```
Store state data to be available globally at the project scope
```{.wrap}
project.info = {data:yourData} => project.info.data
```
Store the intent match score
```{.wrap}
p.score
```
Store data to be passed between contexts
```{.wrap}
p.state.data
```
Store visual context data to be passed from the client app with `setVisualState()`
```{.wrap}
p.visual.data
```
Store user-specific state data to be accessible during the dialog session
```{.wrap}
p.userData.data
```
### Predefined callbacks
Define actions to be performed when the script is saved and dialog model is built
```{.wrap}
onCreateProject(() => { action })
```
Define actions to be performed when the dialog session starts
```{.wrap}
onCreateUser((p) => { action })
```
Define actions to be performed when the dialog session ends
```{.wrap}
onCleanupUser((p) => { action })
```
Define actions to be performed when the visual state is set
```{.wrap}
onVisualState((p, s) => { action })
```
Define actions to be performed when a user event is triggered in the client app: `buttonReady`, `buttonClicked`,
`micPermissionPrompt`, `micAllowed`, `firstActivate`, `showPopup`, `popupCloseClicked`, `recognized`
```{.wrap}
onUserEvent((p, e) => { action })
```
Define actions to be performed when a context is activated
```{.wrap}
onEnter((p) => { action })
```
### Q&A service
Define a URL of a resource to be indexed
```{.wrap}
corpus({url: url, depth: depthLevel})
```
Define text corpus to be used by the assistant in the dialog
```{.wrap}
corpus('text')
```
### Built-in JS libraries
Make API calls
```{.wrap}
axios, request
```
Work with time
```{.wrap}
moment-timezone, luxon
```
Work with arrays, numbers, objects, strings and so on
```{.wrap}
lodash
```
### Other
Provide a list of hints to help recognize specific terms
```{.wrap}
recognitionHints('hint'[, 'hintN'])
```
Write info messages to Alan Studio logs
```{.wrap}
console.log(data)
```
Write error messages to Alan Studio logs
```{.wrap}
console.error(data)
```
## Client SDK
### Client API methods
Send information about the visual state from the client app to the dialog script
```{.wrap}
setVisualState(visualStateData:object)
```
Send data or perform actions without a voice/text command
```{.wrap}
projectAPI.method = function(p, param, callback) {
p.userData.data = param.data;
callback();
};
callProjectApi(method:string, data:object, callback:function)
```
Play a text message in the client app
```{.wrap}
playText(text:string)
```
Send a text message to Alan as the user’s input
```{.wrap}
sendText(text:string)
```
Execute a command in the client app
```{.wrap}
playCommand(command:object)
```
### Client API methods (continued)
Activate the Alan button programmatically
```{.wrap}
activate()
```
Deactivate the Alan button programmatically
```{.wrap}
deactivate()
```
Check the Alan button state
```{.wrap}
isActive()
```
Remove the Alan button from the parent element, page (supported on Web, Ionic)
```{.wrap}
remove()
```
Check the state of the wake word (supported on iOS, Android)
```{.wrap}
getWakewordEnabled()
```
Set the state of the wake word (supported on iOS, Android)
```{.wrap}
setWakewordEnabled(enabled:boolean)
```
### Handlers
// Examples are provided for the Web platform
Handle commands sent from the dialog script to the client app
```{.wrap}
onCommand: function (commandData) { action }
```
Handle Alan button state changes
```{.wrap}
onButtonState: function (e) { action }
```
Handle connection status to the virtual assistant project in the Alan Cloud
```{.wrap}
onConnectionStatus: function (e) { action }
```
Handle events received from Alan
```{.wrap}
onEvent: function (e) { action }
```
## Also see
- [Alan AI website](https://alan.app)
- [About the Alan Platform](https://alan.app/platform)
- [Alan AI documentation](https://alan.app/docs)