nico 8 gadi atpakaļ
vecāks
revīzija
c560a7b78e
5 mainītis faili ar 90 papildinājumiem un 15 dzēšanām
  1. 4 1
      Docs/brain.md
  2. 44 4
      Docs/contributing.md
  3. 8 9
      Docs/kalliope_cli.md
  4. 2 1
      Docs/neurons.md
  5. 32 0
      Docs/signals.md

+ 4 - 1
Docs/brain.md

@@ -9,7 +9,7 @@ An input action, called a "[signal](signals.md)" can be:
 - **an event:** A date or a frequency (E.G: repeat each morning at 8:30)
 - **an event:** A date or a frequency (E.G: repeat each morning at 8:30)
 
 
 An output action is
 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 a complex Ansible playbook.
+- **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.
 
 
 Brain is expressed in YAML format (see YAML Syntax) and has a minimum of syntax, which intentionally tries to not be a programming language or script, 
 Brain is expressed in YAML format (see YAML Syntax) and has a minimum of syntax, which intentionally tries to not be a programming language or script, 
 but rather a model of a configuration or a process.
 but rather a model of a configuration or a process.
@@ -134,4 +134,7 @@ You can provide a default synapse in case none of them are matching when an orde
 ## Next: Start Kalliope
 ## Next: Start Kalliope
 Now you take a look into the [CLI documentation](kalliope_cli.md) to learn how to start kalliope.
 Now you take a look into the [CLI documentation](kalliope_cli.md) to learn how to start kalliope.
 
 
+## Notes
+- What is a [neuron](neurons.md)
+- What is a [signal](signals.md)
 
 

+ 44 - 4
Docs/contributing.md

@@ -58,10 +58,10 @@ The constructor has a __**kwargs argument__ which is corresponding to the Dict o
     ```
     ```
 
 
 1. You must run unit tests with success before sending a pull request. Add new tests that cover the code you want to publish.
 1. You must run unit tests with success before sending a pull request. Add new tests that cover the code you want to publish.
-```
-cd /path/to/kalliope
-python -m unittest discover
-```
+    ```
+    cd /path/to/kalliope
+    python -m unittest discover
+    ```
 
 
 1. (*optionnal-> good practice*) The Neuron can implement a __private method _is_parameters_ok(self)__ which checks if entries are ok. *return: true if parameters are ok, raise an exception otherwise*
 1. (*optionnal-> good practice*) The Neuron can implement a __private method _is_parameters_ok(self)__ which checks if entries are ok. *return: true if parameters are ok, raise an exception otherwise*
 1. (*optionnal-> good practice*) The Neuron can __import and raise exceptions__ coming from NeuronModule:
 1. (*optionnal-> good practice*) The Neuron can __import and raise exceptions__ coming from NeuronModule:
@@ -71,6 +71,46 @@ python -m unittest discover
 1. The Neuron can use a __self.say(message) method__ to speak out some return values using the *say_template* attribute in the brain file.
 1. The Neuron can use a __self.say(message) method__ to speak out some return values using the *say_template* attribute in the brain file.
 the message variable must be a Dict of variable:values where variables can be defined as output.
 the message variable must be a Dict of variable:values where variables can be defined as output.
 
 
+1. Example of neuron structure
+    ```
+    myneuron/
+    ├── __init__.py
+    ├── myneuron.py
+    ├── README.md
+    └── tests
+        ├── __init__.py
+        └── test_myneuron.py
+    ```
+
+1. Example of neuron code
+    ```
+    class Myneuron(NeuronModule):
+    def __init__(self, **kwargs):
+        super(Myneuron, self).__init__(**kwargs)
+        # ge args from the neuron configuration
+        self.arg1 = kwargs.get('arg1', None)
+        self.arg2 = kwargs.get('arg2', None)
+
+        # check if parameters have been provided
+        if self._is_parameters_ok():
+            # -------------------
+            # do amazing code
+            # -------------------            
+
+    def _is_parameters_ok(self):
+        """
+        Check if received parameters are ok to perform operations in the neuron
+        :return: true if parameters are ok, raise an exception otherwise
+
+        .. raises:: MissingParameterException
+        """
+        if self.arg1 is None:
+            raise MissingParameterException("You must specify a arg1")
+        if not isinstance(self.arg2, int):
+            raise MissingParameterException("arg2 must be an integer")
+        return True
+    ```
+
 ##### Constraints
 ##### Constraints
 
 
 1. The Neuron must (as much as possible) ensure the i18n. This means that they should __not manage a specific languages__ inside its own logic.
 1. The Neuron must (as much as possible) ensure the i18n. This means that they should __not manage a specific languages__ inside its own logic.

+ 8 - 9
Docs/kalliope_cli.md

@@ -3,13 +3,12 @@
 ## SYNOPSIS
 ## SYNOPSIS
 This is the syntax used to run Kalliope from command line
 This is the syntax used to run Kalliope from command line
 ```
 ```
-cd /path/to/kalliope
-python kalliope.py command --option <argument>
+kalliope command --option <argument>
 ```
 ```
 
 
 For example, to start Kalliope we simply use
 For example, to start Kalliope we simply use
 ```
 ```
-python kalliope.py start
+kalliope start
 ```
 ```
 
 
 ## ARGUMENTS
 ## ARGUMENTS
@@ -19,7 +18,7 @@ Start Kalliope main program
 
 
 Example of use
 Example of use
 ```
 ```
-python kalliope.py start
+kalliope start
 ```
 ```
 
 
 To kill Kalliope, you can press "Ctrl-C" on your keyboard.
 To kill Kalliope, you can press "Ctrl-C" on your keyboard.
@@ -30,7 +29,7 @@ The GUI allows you to test your [STT](stt.md) and [TTS](tts.md) that you have co
 
 
 Example of use
 Example of use
 ```
 ```
-python kalliope.py gui
+kalliope gui
 ```
 ```
 
 
 ## OPTIONS
 ## OPTIONS
@@ -43,7 +42,7 @@ Run a specific synapse from the brain file.
 
 
 Example of use
 Example of use
 ```
 ```
-python kalliope.py start --run-synapse "say hello"
+kalliope start --run-synapse "say-hello"
 ```
 ```
 
 
 ### --brain-file BRAIN_FILE
 ### --brain-file BRAIN_FILE
@@ -53,12 +52,12 @@ Replace the default brain file from the root of the project folder by a custom o
 
 
 Example of use
 Example of use
 ```
 ```
-python kalliope.py start --brain-file /home/me/my_other_brain.yml
+kalliope start --brain-file /home/me/my_other_brain.yml
 ```
 ```
 
 
 You can combine the options together like, for example:
 You can combine the options together like, for example:
 ```
 ```
-python kalliope.py start --run-synapse "say hello" --brain-file /home/me/my_other_brain.yml
+kalliope start --run-synapse "say-hello" --brain-file /home/me/my_other_brain.yml
 ```
 ```
 
 
 ### --debug
 ### --debug
@@ -67,5 +66,5 @@ Show debug output in the console
 
 
 Example of use
 Example of use
 ```
 ```
-python kalliope.py start --debug
+kalliope start --debug
 ```
 ```

+ 2 - 1
Docs/neurons.md

@@ -55,6 +55,7 @@ From the captured order:
 Here, the spoken value captured by the TTS engine will be passed as an argument to the neuron in the variable named `parameter3`.
 Here, the spoken value captured by the TTS engine will be passed as an argument to the neuron in the variable named `parameter3`.
 
 
 Example, with the synapse declaration above, if you say "this is an order with the parameter Amy Winehouse". The neuron will receive a parameter named `parameter3` with "Amy Winehouse" as a value of this parameter.
 Example, with the synapse declaration above, if you say "this is an order with the parameter Amy Winehouse". The neuron will receive a parameter named `parameter3` with "Amy Winehouse" as a value of this parameter.
+We recommend the reading of the [signals documentation](signals.md) for a complete understanding of how arguments in a neuron work.
 
 
 
 
 ## Output values
 ## Output values
@@ -110,7 +111,7 @@ As this is multi-lines, we can put the content in a file and use a `file_templat
 ## Overridable parameters
 ## Overridable parameters
 
 
 For each neuron, you can override some parameters to use a specific configuration of TTS instead of the default one 
 For each neuron, you can override some parameters to use a specific configuration of TTS instead of the default one 
-set in [settings.yml](settings.yml) file.
+set in [settings.yml](settings.md) file.
 
 
 ### Cache
 ### Cache
 
 

+ 32 - 0
Docs/signals.md

@@ -10,6 +10,7 @@ signals:
 
 
 ## Order
 ## Order
 
 
+### Simple order
 An **order** signal is a word, or a sentence caught by the microphone and processed by the STT engine.
 An **order** signal is a word, or a sentence caught by the microphone and processed by the STT engine.
 
 
 Syntax:
 Syntax:
@@ -32,6 +33,37 @@ For example, if you say "Kalliope please do this", the SST engine can return "ca
 > For example, you have "test my umbrella" in a synapse A and "test" in a synapse B. When you'll say "test my umbrella", both synapse A and B
 > For example, you have "test my umbrella" in a synapse A and "test" in a synapse B. When you'll say "test my umbrella", both synapse A and B
 will be started by Kalliope. So keep in mind that the best practice is to use really different sentences with more than one word for your order.
 will be started by Kalliope. So keep in mind that the best practice is to use really different sentences with more than one word for your order.
 
 
+### Order with arguments
+You can add one or more arguments to an order by adding bracket to the sentence.
+
+Syntax:
+```
+signals:
+    - order: "<sentence> {{ arg_name }}"
+    - order: "<sentence> {{ arg_name }} <sentence>"
+    - order: "<sentence> {{ arg_name }} <sentence> {{ arg_name }}"
+```
+
+Example:
+```
+signals:
+    - order: "I want to listen {{ artist_name }}"
+    - order: "start the {{ episode_number }} episode"
+    - order: "give me the weather at {{ location }} for {{ date }}"
+```
+
+Here, an example order would be speaking out loud the order: "I want to listen Amy Winehouse"
+In this example, both word "Amy" and "Winehouse" will be passed as an unique argument called `artist_name` to the neuron.
+
+If you want to send more than one argument, you must split your argument with a word that Kalliope will use to recognise the start and the end of each arguments.
+For example:  "give me the weather at {{ location }} for {{ date }}"
+And the order would be: "give me the weather at Paris for tomorrow"
+And so, it will word too with: "give me the weather at St-Pierre de Chartreuse for tomorrow"
+
+See the **input values** section of the [neuron documentation](neurons) to know how to send argument to a neuron.
+
+>**Important note:** The following syntax cannot be used: "<sentence> {{ arg_name }} {{ arg_name2 }}" as Kalliope cannot know when a block starts and when it finishes.
+
 ## Event
 ## Event
 
 
 An event is a way to schedule the launching of a synapse periodically at fixed times, dates, or intervals.
 An event is a way to schedule the launching of a synapse periodically at fixed times, dates, or intervals.