mirror of
https://github.com/Fechin/reference.git
synced 2026-11-20 21:23:11 +03:00
503 lines
8.5 KiB
Markdown
503 lines
8.5 KiB
Markdown
---
|
||
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)
|