|
@@ -1,5 +1,16 @@
|
|
|
# Neurons
|
|
|
|
|
|
+- [Neurons](#neurons)
|
|
|
+ - [Usage](#usage)
|
|
|
+ - [Input values](#input-values)
|
|
|
+ - [Output values](#output-values)
|
|
|
+ - [kalliope_memory](#kalliopememory)
|
|
|
+ - [Store parameters generated by a neuron](#store-parameters-generated-by-a-neuron)
|
|
|
+ - [Store parameters captured from orders](#store-parameters-captured-from-orders)
|
|
|
+ - [Get the last order generated TTS message](#get-the-last-order-generated-tts-message)
|
|
|
+ - [Overridable parameters](#overridable-parameters)
|
|
|
+ - [TTS](#tts)
|
|
|
+
|
|
|
A neuron is a plugin that performs a specific action. You use it to create a synapse.
|
|
|
You can add as many neurons as you want to a synapse. The neurons are executed one by one when the input order is triggered.
|
|
|
If you want to install a community neuron, see the [neuron list documentation](neuron_list.md).
|
|
@@ -74,7 +85,7 @@ We recommend the reading of the [signals documentation](signals.md) for a comple
|
|
|
|
|
|
Some neurons will return variables into a dictionary of value. Those values can be used to make your own Kalliope answer through a template.
|
|
|
The objective of using a template is to let the user choosing what he wants to make Kalliope saying in its own language.
|
|
|
-A template is a text file that contains **variables**, which get replaced with values when the template is evaluated by
|
|
|
+A template is a text file that contains **variables**, which get replaced with values when the template is evaluated by
|
|
|
the [template engine](https://en.wikipedia.org/wiki/Jinja_(template_engine)), and **tags**, which control the logic of the template.
|
|
|
|
|
|
The template engine used in Kalliope is [Jinja2](http://jinja.pocoo.org/docs/dev/).
|
|
@@ -97,7 +108,7 @@ Placed in a complete synapse, it looks like the following
|
|
|
- "It is {{ hours }} hours and {{ minutes }} minutes"
|
|
|
```
|
|
|
|
|
|
-Here, we use [variables](http://jinja.pocoo.org/docs/dev/templates/#variables) from the neuron into our template file. Both variables will be interpreted by the template engine.
|
|
|
+Here, we use [variables](http://jinja.pocoo.org/docs/dev/templates/#variables) from the neuron into our template file. Both variables will be interpreted by the template engine.
|
|
|
So, what the user will hear is something like `It is 9 hours and 21 minutes`.
|
|
|
|
|
|
We can add some logic to a template with tags. Here a simple example with [a test tag](http://jinja.pocoo.org/docs/dev/templates/#if), that will make Kalliope change the pronounced sentence depending on the current time.
|
|
@@ -119,9 +130,9 @@ As this is multi-lines, we can put the content in a file and use a `file_templat
|
|
|
file_template: /path/to/file/template.j2
|
|
|
```
|
|
|
|
|
|
-## kalliope_memory: Store in memory a variable from an order or generated from a neuron
|
|
|
+## kalliope_memory
|
|
|
|
|
|
-Kalliope can store in a short term memory:
|
|
|
+Kalliope can store in a short term memory a variable from an order or generated from a neuron:
|
|
|
- output parameters from a neuron
|
|
|
- variable parameters captured from an order.
|
|
|
|
|
@@ -136,7 +147,7 @@ Syntax with output parameters from a neuron
|
|
|
signals:
|
|
|
- order: "my order"
|
|
|
neurons:
|
|
|
- - neuron_name:
|
|
|
+ - neuron_name:
|
|
|
kalliope_memory:
|
|
|
key_name_in_memory: "{{ output_variable_from_neuron }}"
|
|
|
other_key_name_in_memory: "{{ other_output_variable_from_neuron }}"
|
|
@@ -150,10 +161,10 @@ Syntax to reuse memorized parameters in another synapse
|
|
|
neurons:
|
|
|
- neuron_name:
|
|
|
parameter1: "{{ kalliope_memory['key_name_in_memory'] }}"
|
|
|
- parameter2: "{{ kalliope_memory['other_key_name_in_memory'] }}"
|
|
|
+ parameter2: "{{ kalliope_memory['other_key_name_in_memory'] }}"
|
|
|
```
|
|
|
|
|
|
->**Note:** The key name need to be placed into simple quotes
|
|
|
+>**Note:** The key name need to be placed into simple quotes
|
|
|
|
|
|
|
|
|
Example with a core neuron like `systemdate`
|
|
@@ -164,7 +175,7 @@ Example with a core neuron like `systemdate`
|
|
|
neurons:
|
|
|
- systemdate:
|
|
|
say_template:
|
|
|
- - "It' {{ hours }} hours and {{ minutes }} minutes"
|
|
|
+ - "It' {{ hours }} hours and {{ minutes }} minutes"
|
|
|
kalliope_memory:
|
|
|
hours_when_asked: "{{ hours }}"
|
|
|
minutes_when_asked: "{{ minutes }}"
|
|
@@ -193,7 +204,7 @@ Multiple parameters can be used and concatenated in the same memorized key
|
|
|
```yml
|
|
|
kalliope_memory:
|
|
|
my_saved_key: "{{ neuron_parameter_name1 }} and {{ neuron_parameter_name2 }}"
|
|
|
-```
|
|
|
+```
|
|
|
|
|
|
### Store parameters captured from orders
|
|
|
|
|
@@ -203,9 +214,9 @@ Syntax
|
|
|
signals:
|
|
|
- order: "my order with {{ variable }}"
|
|
|
neurons:
|
|
|
- - neuron_name:
|
|
|
+ - neuron_name:
|
|
|
kalliope_memory:
|
|
|
- key_name_in_memory: "{{ variable }}"
|
|
|
+ key_name_in_memory: "{{ variable }}"
|
|
|
```
|
|
|
|
|
|
The syntax to reuse memorized parameters in another synapse is the same as the one used with neuron parameters
|
|
@@ -215,7 +226,7 @@ The syntax to reuse memorized parameters in another synapse is the same as the o
|
|
|
- order: "an order"
|
|
|
neurons:
|
|
|
- neuron_name:
|
|
|
- parameter1: {{ kalliope_memory['key_name_in_memory']}}
|
|
|
+ parameter1: {{ kalliope_memory['key_name_in_memory']}}
|
|
|
```
|
|
|
|
|
|
Example
|
|
@@ -240,7 +251,7 @@ The value can now be used in a next call like the following
|
|
|
neurons:
|
|
|
- say:
|
|
|
message:
|
|
|
- - "It's {{ kalliope_memory['friend'] }}
|
|
|
+ - "It's {{ kalliope_memory['friend'] }}
|
|
|
```
|
|
|
|
|
|
Here is another example brain whit use the `neurotimer` neuron. In this scenario, you want to remember to do something
|
|
@@ -276,24 +287,24 @@ Here is another example brain whit use the `neurotimer` neuron. In this scenario
|
|
|
### Get the last order generated TTS message
|
|
|
|
|
|
Kalliope will save in memory automatically:
|
|
|
-- the last generated TTS message .
|
|
|
+- the last generated TTS message .
|
|
|
- the last caught order
|
|
|
|
|
|
To get the last generated message, use the key `{{ kalliope_memory['kalliope_last_tts_message'] }}` in your synapse.
|
|
|
To get the last order, use the key `{{ kalliope_memory['kalliope_last_order'] }}` in your synapse.
|
|
|
|
|
|
-Keep in mind that the `kalliope_last_tts_message` variable is overridden every time Kalliope says something.
|
|
|
+Keep in mind that the `kalliope_last_tts_message` variable is overridden every time Kalliope says something.
|
|
|
So you need to catch messages you want to process in the right hook like `on_start_speaking` or `on_stop_speaking`.
|
|
|
|
|
|
-An example of usage is to send each message to an API each time Kalliope start speaking.
|
|
|
+An example of usage is to send each message to an API each time Kalliope start speaking.
|
|
|
|
|
|
You need at first to create a hook in your `settings.yml` like the following
|
|
|
```yml
|
|
|
-hooks:
|
|
|
+hooks:
|
|
|
on_start_speaking: "mm-say"
|
|
|
```
|
|
|
|
|
|
-Then create a synapse in your `brain` that is linked to the hook to send each message.
|
|
|
+Then create a synapse in your `brain` that is linked to the hook to send each message.
|
|
|
As a concrete example, here the [magic mirror neuron](https://github.com/kalliope-project/kalliope_neuron_magic_mirror) is used to send each spelt out loud message to the Magic Mirror API in order to show them on the screen.
|
|
|
```yml
|
|
|
- name: "mm-say"
|
|
@@ -307,8 +318,8 @@ As a concrete example, here the [magic mirror neuron](https://github.com/kalliop
|
|
|
|
|
|
**Note**
|
|
|
|
|
|
-`kalliope_last_tts_message` is overridden each time Kalliope says something.
|
|
|
-For example, a common practice is to have a synapse placed in the hook `on_triggered` in order to know when the hotword has been triggered.
|
|
|
+`kalliope_last_tts_message` is overridden each time Kalliope says something.
|
|
|
+For example, a common practice is to have a synapse placed in the hook `on_triggered` in order to know when the hotword has been triggered.
|
|
|
So, if this synapse is configured like the following
|
|
|
```yml
|
|
|
- name: "on-triggered-synapse"
|
|
@@ -356,7 +367,7 @@ text_to_speech:
|
|
|
cache: True
|
|
|
```
|
|
|
|
|
|
-And this is how I override only the cache parameter.
|
|
|
+And this is how I override only the cache parameter.
|
|
|
```yml
|
|
|
- systemdate:
|
|
|
say_template:
|
|
@@ -375,7 +386,7 @@ You can override all parameter for each neurons like in the example bellow
|
|
|
- say:
|
|
|
message:
|
|
|
- "Buenos dias"
|
|
|
- tts:
|
|
|
+ tts:
|
|
|
pico2wave:
|
|
|
language: "es-ES"
|
|
|
cache: False
|