Browse Source

add kalliope_memory doc

nico 7 years ago
parent
commit
894e8c5226
3 changed files with 157 additions and 2 deletions
  1. 3 0
      Docs/brain.md
  2. 154 1
      Docs/neurons.md
  3. 0 1
      kalliope/core/NeuronModule.py

+ 3 - 0
Docs/brain.md

@@ -7,6 +7,9 @@ Brain is composed by synapses: a synapse is the link between input and output ac
 An input action, called a "[signal](signals.md)" can be:
 - **an order:** Something that has been spoke out loud by the user.
 - **an event:** A date or a frequency (E.G: repeat each morning at 8:30)
+- **a mqtt message** A message received on a MQTT topic
+- A signal made the community
+- **No signal**. Then the synapse can be only called from another synapse or by the API
 
 An output action is
 - **a list of neurons:** A [neuron](neurons.md) is a module or plugin that will perform some actions like simply talking, run a script, run a command or call a web service.

+ 154 - 1
Docs/neurons.md

@@ -119,6 +119,160 @@ 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 can store in a short term memory:
+- output parameters from a neuron
+- variable parameters captured from an order.
+
+Stored parameters can then be used in other synapses during a future call.
+Please not that this memory is not preserved after a restart of Kalliope.
+
+### Store parameters generated by a neuron
+
+Syntax with output parameters from a neuron
+```yml
+- name: "synapse-name"
+  signals:
+    - order: "my order"
+  neurons:
+    - neuron_name:        
+        kalliope_memory:
+          key_name_in_memory: "{{ output_variable_from_neuron }}"
+          other_key_name_in_memory: "{{ other_output_variable_from_neuron }}"
+```
+
+Syntax to reuse memorized parameters in another synapse
+```yml
+- name: "synapse-name"
+  signals:
+    - order: "an order"
+  neurons:
+    - neuron_name:
+        parameter1: "{{ kalliope_memory['key_name_in_memory'] }}"
+        parameter2: "{{ kalliope_memory['other_key_name_in_memory'] }}"        
+```
+
+>**Note:** The key name need to be placed into simple quotes 
+
+
+Example with a core neuron like `systemdate`
+```yml
+- name: "synapse-name"
+  signals:
+    - order: "my order"
+  neurons:
+    - systemdate:
+        say_template:
+          - "It' {{ hours }} hours and {{ minutes }} minutes"         
+        kalliope_memory:
+          hours_when_asked: "{{ hours }}"
+          minutes_when_asked: "{{ minutes }}"
+```
+
+Here, the `systemdate` neuron generates variables that haven been passed to the template like described in the previous section and to the memory of Kalliope.
+
+Those parameters can now be used in a next call
+```yml
+- name: "synapse-name-2"
+  signals:
+    - order: "a what time I've asked the time?"
+  neurons:
+    - say:
+        message:
+          - "at {{ kalliope_memory['hours_when_asked']}} hours and {{ kalliope_memory['minutes_when_asked']}} minutes"
+```
+
+As it's based on a template, the value can be modified by adding a string
+```yml
+kalliope_memory:
+  my_saved_key: "{{ neuron_parameter_name }} with a word"
+```
+
+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
+
+Syntax
+```yml
+- name: "synapse-name"
+  signals:
+    - order: "my order with {{ variable }}"
+  neurons:
+    - neuron_name:        
+        kalliope_memory:
+          key_name_in_memory: "{{ variable }}"         
+```
+
+The syntax to reuse memorized parameters in another synapse is the same as the one used with neuron parameters
+```yml
+- name: "synapse-name"
+  signals:
+    - order: "an order"
+  neurons:
+    - neuron_name:
+        parameter1: {{ kalliope_memory['key_name_in_memory']}}               
+```
+
+Example
+```yml
+- name: "synapse-id"
+  signals:
+    - order: "say hello to {{ name }}"
+  neurons:
+    - say:
+        message:
+          - "Hello {{ name }}"
+        kalliope_memory:
+          friend: "{{ name }}"
+```
+
+Here, the variable "name" has been used directly into the template and also saved in memory behind the key "friend".
+The value can now be used in a next call like the following
+```yml
+- name: "synapse-id"
+  signals:
+    - order: "what is the name of my friend?"
+  neurons:
+    - say:
+        message:
+          - "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
+
+> **You:** remind me to call mom in 15 minutes<br>
+**Kalliope:** I'll notify you in 15 minutes<br>
+15 minutes later..<br>
+**Kalliope:** You asked me to remind you to call mom 15 minutes ago
+
+```yml
+- name: "remember-synapse"
+  signals:
+    - order: "remind me to {{ remember }} in {{ time }} minutes"
+  neurons:
+    - neurotimer:
+        seconds: "{{ time }}"
+        synapse: "remember-todo"
+        kalliope_memory:
+          remember: "{{ remember }}"
+          seconds: "{{ time }}"
+    - say:
+        message:
+          - "I'll remind you in {{ time }} minutes"
+
+- name: "remember-todo"
+  signals: {}
+  neurons:
+    - say:
+        message:
+          - "You asked me to remind you to {{ kalliope_memory['remember'] }} {{ kalliope_memory['time'] }} minutes ago"
+```
+
 
 ## Overridable parameters
 
@@ -172,4 +326,3 @@ You can override all parameter for each neurons like in the example bellow
 ```
 
 >**Note:** The TTS must has been configured with its required parameters in the settings.yml file to be overridden. See [TTS documentation](tts.md).
-

+ 0 - 1
kalliope/core/NeuronModule.py

@@ -194,7 +194,6 @@ class NeuronModule(object):
         .. raises:: TemplateFileNotFoundException
         """
         returned_message = None
-        print(message_dict)
         # the user chooses a say_template option
         if self.say_template is not None:
             returned_message = self._get_say_template(self.say_template, message_dict)