Skip to content
This repository was archived by the owner on Apr 24, 2025. It is now read-only.

Commit b2ad305

Browse files
jankoenigjankoenig
authored
🔀 Merge pull request #92 from rmtuckerphx/v4/docs/snips
📝 Update README with Snips customization of Jovo model
2 parents c66c59b + 9f95274 commit b2ad305

File tree

3 files changed

+502
-1
lines changed

3 files changed

+502
-1
lines changed

‎packages/jovo-model-snips/README.md

Lines changed: 220 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ Learn how to turn the Jovo Model into a Snips NLU model.
44

55
- [Introduction](#introduction)
66
- [Using the Snips Jovo Model npm Package](#using-the-snips-jovo-model-npm-package)
7+
- [Customizing the Jovo Model](#customizing-the-jovo-model)
78

89
## Introduction
910

@@ -20,4 +21,222 @@ Install the package like this:
2021
$ npm install @jovotech/model-snips
2122
```
2223

23-
You can learn more about all the Jovo Model features here: [Using the Jovo Model npm Packages](http://jovo.tech/marketplace/jovo-model#using-the-jovo-model-npm-packages).
24+
You can learn more about all the Jovo Model features here: [Using the Jovo Model npm Packages](http://jovo.tech/marketplace/jovo-model#using-the-jovo-model-npm-packages).
25+
26+
Here is a code sample of how to convert from a Jovo model to a Snips dataset:
27+
28+
```ts
29+
import { JovoModelData } from '@jovotech/model';
30+
import { JovoModelSnips } from '@jovotech/model-snips';
31+
import jovoModel from './models/en.json';
32+
33+
const snipsDataset = JovoModelSnips.fromJovoModel(jovoModel as JovoModelData, 'en');
34+
console.log(JSON.stringify(snipsDataset, null, 2));
35+
```
36+
37+
## Customizing the Jovo Model
38+
39+
For Snips, the Jovo Model supports the following Intent entries:
40+
- [Intent only](#intent-only)
41+
- [Builtin entities](#builtin-entities)
42+
- [Custom entities](#custom-entities)
43+
- [Combined builtin and custom entities](#combined-builtin-and-custom-entities)
44+
45+
Look in the [examples](./examples/) folder to see how to structure a [Jovo model](./examples/basic/jovo4-model-en.json) and the corresponding [Snips dataset](./examples/basic/snips-dataset-en.json) that will be generated.
46+
47+
### Intent only
48+
49+
An intent-only entry includes an array of `phrases`:
50+
51+
```json
52+
// Jovo model
53+
{
54+
"invocation": "my test app",
55+
"version": "4.0",
56+
"intents": {
57+
"YesIntent": {
58+
"phrases": [
59+
"yes",
60+
"yes please",
61+
"sure"
62+
]
63+
}
64+
}
65+
}
66+
```
67+
68+
69+
### Builtin entities
70+
71+
An intent can include an array of `phrases` with `{variables}` that map to a key in the `entities` object.
72+
73+
For a builtin entity, the `type` starts with `"snips/"` followed by the entity type:
74+
75+
```json
76+
// Jovo model
77+
{
78+
"invocation": "my test app",
79+
"version": "4.0",
80+
"intents": {
81+
"NumberIntent": {
82+
"phrases": [
83+
"my number is {myNumber}"
84+
],
85+
"entities": {
86+
"myNumber": {
87+
"type": "snips/number"
88+
}
89+
}
90+
}
91+
}
92+
}
93+
```
94+
95+
For a list of builtin Snips types, see [Supported builtin entities](https://snips-nlu.readthedocs.io/en/latest/builtin_entities.html) and refer to the `Identifier` column.
96+
97+
### Custom entities
98+
99+
An intent can include an array of `phrases` with `{variables}` that map to a key in the `entities` object.
100+
101+
For a custom entity, the `type` will be a custom name that you define and a corresponding entry must be added to the `entityTypes` section. Custom entity types can include synonyms:
102+
103+
```json
104+
// Jovo model
105+
{
106+
"invocation": "my test app",
107+
"version": "4.0",
108+
"intents": {
109+
"ColorIntent": {
110+
"phrases": [
111+
"i pick {color}",
112+
"my favorite color is {color}"
113+
],
114+
"entities": {
115+
"color": {
116+
"type": "CUSTOM_COLORS"
117+
}
118+
}
119+
}
120+
},
121+
"entityTypes": {
122+
"CUSTOM_COLORS": {
123+
"name": "CUSTOM_COLORS",
124+
"values": [
125+
{
126+
"value": "red",
127+
"synonyms": [
128+
"crimson"
129+
]
130+
},
131+
{
132+
"value": "yellow",
133+
"synonyms": []
134+
},
135+
{
136+
"value": "blue",
137+
"synonyms": []
138+
},
139+
{
140+
"value": "green",
141+
"synonyms": []
142+
},
143+
{
144+
"value": "orange",
145+
"synonyms": []
146+
},
147+
{
148+
"value": "purple",
149+
"synonyms": []
150+
}
151+
]
152+
}
153+
}
154+
}
155+
```
156+
157+
**NOTICE**: There is a current limitation with the mapping of a Jovo model to a Snips dataset such that the values for `use_synonyms` and `automatically_extensible` are always `true` and `matching_strictness` is always `1`. With `automatically_extensible` set to `true` it means that the data list values provided are not all the values that will be recognized for the entity type.
158+
159+
```json
160+
// Snips dataset (partial)
161+
{
162+
"CUSTOM_COLORS": {
163+
"data": [
164+
{
165+
"value": "red",
166+
"synonyms": [
167+
"crimson"
168+
]
169+
},
170+
{
171+
"value": "yellow",
172+
"synonyms": []
173+
},
174+
{
175+
"value": "blue",
176+
"synonyms": []
177+
},
178+
{
179+
"value": "green",
180+
"synonyms": []
181+
},
182+
{
183+
"value": "orange",
184+
"synonyms": []
185+
},
186+
{
187+
"value": "purple",
188+
"synonyms": []
189+
}
190+
],
191+
"matching_strictness": 1,
192+
"use_synonyms": true,
193+
"automatically_extensible": true
194+
},
195+
}
196+
```
197+
198+
### Combined builtin and custom entities
199+
200+
You can also combine builtin and custom entities for the same intent:
201+
202+
```json
203+
// Jovo model
204+
{
205+
"invocation": "my test app",
206+
"version": "4.0",
207+
"intents": {
208+
"WeatherIntent": {
209+
"phrases": [
210+
"give me the weather forecast for {weatherLocation} {weatherDate}"
211+
],
212+
"entities": {
213+
"weatherLocation": {
214+
"type": "CUSTOM_WEATHER_LOCATION"
215+
},
216+
"weatherDate": {
217+
"type": "snips/datetime"
218+
}
219+
}
220+
}
221+
},
222+
"entityTypes": {
223+
"CUSTOM_WEATHER_LOCATION": {
224+
"name": "CUSTOM_WEATHER_LOCATION",
225+
"values": [
226+
{
227+
"value": "phoenix",
228+
"synonyms": []
229+
},
230+
{
231+
"value": "los angeles",
232+
"synonyms": []
233+
},
234+
{
235+
"value": "new york city",
236+
"synonyms": []
237+
}
238+
]
239+
}
240+
}
241+
}
242+
```

‎packages/jovo-model-snips/examples/basic/jovo4-model-en.json

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
{
2+
"invocation": "my test app",
3+
"version": "4.0",
4+
"intents": {
5+
"YesIntent": {
6+
"phrases": [
7+
"yes",
8+
"yes please",
9+
"sure"
10+
]
11+
},
12+
"NoIntent": {
13+
"phrases": [
14+
"no",
15+
"no thanks"
16+
]
17+
},
18+
"ColorIntent": {
19+
"phrases": [
20+
"i pick {color}",
21+
"my favorite color is {color}"
22+
],
23+
"entities": {
24+
"color": {
25+
"type": "CUSTOM_COLORS"
26+
}
27+
}
28+
},
29+
"NumberIntent": {
30+
"phrases": [
31+
"my number is {myNumber}"
32+
],
33+
"entities": {
34+
"myNumber": {
35+
"type": "snips/number"
36+
}
37+
}
38+
},
39+
"WeatherIntent": {
40+
"phrases": [
41+
"give me the weather forecast for {weatherLocation} {weatherDate}"
42+
],
43+
"entities": {
44+
"weatherLocation": {
45+
"type": "CUSTOM_WEATHER_LOCATION"
46+
},
47+
"weatherDate": {
48+
"type": "snips/datetime"
49+
}
50+
}
51+
}
52+
},
53+
"entityTypes": {
54+
"CUSTOM_COLORS": {
55+
"name": "CUSTOM_COLORS",
56+
"values": [
57+
{
58+
"value": "red",
59+
"synonyms": [
60+
"crimson"
61+
]
62+
},
63+
{
64+
"value": "yellow",
65+
"synonyms": []
66+
},
67+
{
68+
"value": "blue",
69+
"synonyms": []
70+
},
71+
{
72+
"value": "green",
73+
"synonyms": []
74+
},
75+
{
76+
"value": "orange",
77+
"synonyms": []
78+
},
79+
{
80+
"value": "purple",
81+
"synonyms": []
82+
}
83+
]
84+
},
85+
"CUSTOM_WEATHER_LOCATION": {
86+
"name": "CUSTOM_WEATHER_LOCATION",
87+
"values": [
88+
{
89+
"value": "phoenix",
90+
"synonyms": []
91+
},
92+
{
93+
"value": "los angeles",
94+
"synonyms": []
95+
},
96+
{
97+
"value": "new york city",
98+
"synonyms": []
99+
}
100+
]
101+
}
102+
}
103+
}

0 commit comments

Comments
 (0)