<commit_before># Susi Skill Development Tutorial

Do you want your own AI Skills for Susi? It's surprisingly easy to add more Skills to Susi.

## Getting Started

It's easy, DON'T PANIC. You don't need to be a software developer to enhance Susi.

### What you have to do

We have a Susi Skill develoment environment based on an etherpad. You don't know what an etherpad is? It's a blank web page where you can just put in your text and everyone can colaborate.

* open http://dream.asksusi.com
* name a dream (just pick a name for your tests)
* the etherpad is filled with a welcome message, just delete the content completely

ATTENTION: the Susi Dream zone is a TEMPORARY zone. We may clean up that place at any time. It is only for testing your new Susi Skills
If you want your new Susi Skills to be permanent, send us a pull request, see submitting_skills_to_git.md for a tuturial.

### Preparation to start testing

To test the Skills you are editing, you only need the Susi Android Application (see: https://github.com/fossasia/susi_android )
Or you can also test the Skills online at http://asksusi.com/chat

Within the chat dialog, enter

```
dream <testname>
```

where `<testname>` is the name of the etherpad you just entered in http://dream.asksusi.com

Now all Skills you enter in the dream zone are available instantly in your chat! Thats easy, is it?

To stop testing your new Susi Skills, write `stop dreaming`.

### Tutorial Level 0: Fixed Query-Answer Phrase Collections

In you dream test zone (the etherpad) write:
```
# susi Skill tutorial playground
roses are red
susi is a hack
```
This defines one simple Skill: to answer on "roses are red" the phrase "susi is a hack". The other lines mean:
* all lines starting with `#` are comment lines and are ignored.
* all other text lines define Sikks. Skills are separate with empty lines. Comment and section declaration modifiers count also like empty lines as separator.

Now you can test the new Skill:
* send the following query to Susi: "roses are red"
* Susi will answer with "susi is a hack".
The Skill file is just a text file where two lines which are not separated with an empty line represent a conversation pattern.
You can actually add a third line to your file:
```
# susi tutorial playground
::prior
roses are red
susi is a hack
skynet is back
```
With that file, Susi would respond on "roses are red" the answer "susi is a hack" and on the query "susi is a hack" it would respond "skynet is back". Try it!

### Tutorial Level 1: Random Answers
Skills without a deterministic behavior will create less predictable results.
That can easily be defined with Skills. Lets consider you want a Skill where different answers
on "What is your favorite dish?" are "Potatoes", "Vegetables" or "Fish". Thats easy: add an empty line
to the end of your test file and then:
```
What is your favorite dish
Potatoes|Vegetables|Fish
```

### Tutorial Level 2: Query Alternatives
Maybe you want that Susi responds to several different queries with the same answer. This can be
done very easy with Alternatives in the query line:
```
Bonjour|Buenos días|Ciao
Hello
```

### Tutorial Level 3: Patterns in Queries
In some cases the query lines may be so similar, that you want to use a pattern to declare all possible queries for an answer instead of using fixed alternatives. Query patters can be declared using the "*" wildcard character. A "*" matches any sentence token, but not a substring. That means, a "*" replaces a word or a list of words.

```
May I * you?
Yes you may.
```

### Tutorial Level 4: Using Query-Patterns in Answers
It would be nice if we could use the content of the text which matched with the query patterns.
Every pattern that matched has a pattern number: the first pattern has the number 1 and if 
we want to use that pattern in the result, we can denote that with the term `$1$`:
```
May I get a *?
Yes you may get a $1$!
```
It is of course possible to combine Query-Patterns with alternatives
in the query-part and the response part.

### Tutorial Level 5: Multiple Patterns in Queries and Answers
You can have of course multiple wildcards in the query pattern.
There may be different reasons for that: either it is actually intended
that both wildcards are used in the response or one of the wildcard<commit_msg>Proofread the tutorial up to Level 5<commit_after># Susi Skill Development Tutorial

Do you want your own AI Skills for Susi? It's surprisingly easy to add more Skills to Susi.

## Getting Started

It's easy, DON'T PANIC. You don't need to be a software developer to enhance Susi.

### What you have to do

We have a Susi Skill develoment environment based on an etherpad. You don't know what an etherpad is? It's a blank web page where you can just put in your text and everyone can colaborate.

* open http://dream.asksusi.com
* name a dream (just pick a name for your tests)
* the etherpad is filled with a welcome message, just delete the content completely

ATTENTION: the Susi Dream zone is a TEMPORARY zone. We may clean up that place at any time. It is only for testing your new Susi Skills
If you want your new Susi Skills to be permanent, send us a pull request, see [submitting_skills_to_git.md](submitting_skills_to_git.md) for a tutorial.

### Preparation to start testing

To test the skills you are editing, you only need the Susi Android Application (see: https://github.com/fossasia/susi_android )
Or you can also test the Skills online at http://asksusi.com/chat

Within the chat dialog, enter

```
dream <testname>
```

where `<testname>` is the name of the etherpad you just entered in http://dream.asksusi.com

Now all Skills you enter in the dream zone are available instantly in your chat! Thats easy, is it?

To stop testing your new Susi Skills, write `stop dreaming`.

### Tutorial Level 0: Fixed Query-Answer Phrase Collections

In you dream test zone (the etherpad) write:
```
# susi Skill tutorial playground
roses are red
susi is a hack
```
This defines one simple Skill: to answer on "roses are red" the phrase "susi is a hack". The other lines mean:
* all lines starting with `#` are comment lines and are ignored.
* all other text lines define Skills. Skills are separated by empty lines. Comment and section declaration modifiers also count as empty lines and separate Skills.

Now you can test the new Skill:
* send the following query to Susi: "roses are red"
* Susi will answer with "susi is a hack".
The Skill file is just a text file where two lines which are not separated with an empty line represent a conversation pattern.
You can actually add a third line to your file:
```
# susi tutorial playground
::prior
roses are red
susi is a hack
skynet is back
```
With that file, Susi would respond on "roses are red" the answer "susi is a hack" and on the query "susi is a hack" it would respond "skynet is back". Try it!

### Tutorial Level 1: Random Answers
Skills without a deterministic behavior will create less predictable results.
That can easily be defined with Skills. Lets consider you want a Skill where different answers
on "What is your favorite dish?" are "Potatoes", "Vegetables" or "Fish". Thats easy: add an empty line
to the end of your test file and then:
```
What is your favorite dish
Potatoes|Vegetables|Fish
```

### Tutorial Level 2: Query Alternatives
Maybe you want that Susi responds to several different queries with the same answer. This can be
done very easy with Alternatives in the query line:
```
Bonjour|Buenos días|Ciao
Hello
```

### Tutorial Level 3: Patterns in Queries
In some cases the query lines may be so similar, that you want to use a pattern to declare all possible queries for an answer instead of using fixed alternatives. Query patters can be declared using the `*` wildcard character. A `*` matches any sentence token, but not a substring. That means, a `*` replaces a word or a list of words.

```
May I * you?
Yes you may.
```

### Tutorial Level 4: Using Query-Patterns in Answers
It would be nice if we could use the content of the text which matched with the query patterns.
Every pattern that matched has a pattern number: the first pattern has the number 1 and if 
we want to use that pattern in the result, we can denote that with the term `$1$`:
```
May I get a *?
Yes you may get a $1$!
```
It is of course possible to combine Query-Patterns with alternatives
in the query-part and the response part.

### Tutorial Level 5: Multiple Patterns in Queries and Answers
You can have of course multiple wildcards in the query pattern.
There may be different reasons for that: either it is actually intended
that both wildcards are used in the response or one of the wildcard
{'fraction_non_alphanumeric': 0.05799607978784734, 'fraction_numerical': 0.0021907067911910525, 'mean_word_length': 4.209609609609609, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3855354', 'n_tokens_mistral': 2485, 'n_tokens_neox': 2308, 'n_words': 1436}