Merge pull request #134 from kalliope-project/dev

v0.3.0 GA

.travis.yml

@@ -0,0 +1,14 @@
+language: python
+python:
+  - "2.7"
+# command to install dependencies
+before_install:
+- sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu trusty main restricted universe multiverse"
+- sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu trusty-updates main restricted universe multiverse"
+- sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu trusty-backports main restricted universe multiverse"
+- sudo apt-get update
+- sudo apt-get install $(cat install/files/deb-packages_requirements.txt)
+- sudo apt-get install libstdc++6
+install: "pip install -r install/files/python_requirements.txt"
+# command to run tests
+script: pytest

CHANGELOG.md

@@ -1,3 +1,15 @@
+v0.3.0 / 2016-12-7
+=================
+- add unit tests for core & neurons
+- add CI (Travis)
+- refactor Event manager
+- support installation with setup.py
+- support pip installation
+- fix ansible_playbook neuron
+- add rss_reader neuron
+- review settings and brain file loading
+- add default neuron used if Kalliope does not match the spelt order
+
 v0.2 / 2016-11-21
 =================
 

Docs/brain.md

@@ -1,6 +1,6 @@
 # Brain
 
-The brain is a main component of Kalliope. It's a module that gives a confuguration of your own personal assistant and, so, determines it's behavior and fonctionnalities.
+The brain is a main component of Kalliope. It's a module that gives a configuration of your own personal assistant and, so, determines it's behavior and fonctionnalities.
 
 Brain is composed by synapses: a synapse is the link between input and output actions.
 
@@ -9,10 +9,14 @@ 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 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, 
 but rather a model of a configuration or a process.
+Kalliope will look for the brain in the order bellow:
+- From you current folder, E.g `/home/pi/my_kalliope/brain.yml`
+- From `/etc/kalliope/brain.yml`
+- From the default `brain.yml`. You can take a look into the default [`brain.yml`](../kalliope/brain.yml) file which is located in the root of the project tree.
 
 Let's take a look on a basic synapse in our brain:
 
@@ -28,11 +32,7 @@ Let's take a look on a basic synapse in our brain:
 
 Let's break this down in sections so we can understand how the file is built and what each part means.
 
-The file starts with:
-```
----
-```
-This is a requirement for YAML to interpret the file as a proper document.
+The file starts with: `---`. This is a requirement for YAML to interpret the file as a proper document.
 
 Items that begin with a ```-``` are considered as list items. Items have the format of ```key: value``` where value can be a simple string or a sequence of other items.
 
@@ -95,7 +95,7 @@ neurons:
 Note here that parameters are indented with one tabulation bellow the neuron's name (YAML syntax requirement).
 
 In this example, the neuron called "say" will make Kalliope speak out loud the sentence in parameter **message**.
-See the complete list of [available neurons](neurons.md) here.
+See the complete list of [available neurons](neuron_list.md) here.
 
 ## Manage synapses
 
@@ -108,15 +108,13 @@ If you want a better visibly, or simply sort your actions in different files, yo
 
 To do that, use the import statement in the entry brain.yml file with the following syntax:
 ```
----
   - includes:
       - path/to/sub_brain.yml
       - path/to/another_sub_brain.yml
 ```
 
 E.g:
 ```
----
   - includes:
       - brains/rolling_shutter_commands.yml
       - brains/find_my_phone.yml
@@ -125,3 +123,18 @@ E.g:
 >**Note:** You can only use the `include` statement in the main brain file. 
 
 >**Note:** the includes statement must start with a `-`
+
+
+## The default Synapse
+
+You can provide a default synapse in case none of them are matching when an order is given.
+>**Note:** This default synapse is optional.
+>**Note:** You need to define it in the settings.yml cf :[Setting](settings.md).
+
+## Next: 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)
+

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.
-```
-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 __import and raise exceptions__ coming from NeuronModule:
@@ -71,9 +71,49 @@ 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.
 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)
+        # the 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
 
-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 language__ inside its own logic.
 Only [Synapse](brain.md) by the use of [Order](signals.md) must interact with the languages. This allow a Neuron to by reused by anyone, speaking any language.
 
 1. Respect [PEP 257](https://www.python.org/dev/peps/pep-0257/) -- Docstring conventions. For each class or method add a description with summary, input parameter, returned parameter,  type of parameter

Docs/installation.md

@@ -0,0 +1,121 @@
+# Kalliope installation
+
+## Prerequisites
+
+Please follow the right link bellow to install requirements depending on your target environment:
+- [Raspbian (Raspberry Pi 2 & 3)](installation/raspbian_jessie.md)
+- [Ubuntu 14.04/16.04](installation/ubuntu_16.04.md)
+- [Debian Jessie](installation/debian_jessie.md)
+
+## Installation
+
+### Method 1 - User install using the PIP package
+
+You can install kalliope on your system by using Pypi:
+```
+sudo pip install kalliope
+```
+
+### Method 2 - Manual setup using sources
+
+Clone the project:
+```
+git clone https://github.com/kalliope-project/kalliope.git
+cd kalliope
+```
+
+Install the project:
+```
+sudo python setup.py install
+```
+
+### Method 3 - Developer install using Virtualenv
+
+Install the `python-virtualenv` package:
+```
+sudo apt-get install python-virtualenv
+```
+
+Clone the project:
+```
+git clone https://github.com/kalliope-project/kalliope.git
+cd kalliope
+```
+
+Generate a local python environment:
+```
+virtualenv venv
+```
+
+Install the project using the local environment:
+```
+venv/bin/pip install --editable .
+```
+
+### Method 4 - Developer, dependencies install only
+
+Clone the project:
+```
+git clone https://github.com/kalliope-project/kalliope.git
+cd kalliope
+```
+
+Install the python dependencies directly:
+```
+sudo pip install -r install/python_requirements.txt
+```
+
+## Test your env
+
+To ensure that you can record your voice, run the following command to capture audio input from your microphone:
+```
+rec test.wav
+```
+
+Press CTRL-C after capturing a sample of your voice.
+
+Then play the recorded audio file
+```
+mplayer test.wav
+```
+
+You can then test that your Kalliope is working by using the "bonjour" order integrated in the [default brain](../kalliope/brain.yml).
+Start kalliope:
+```
+kalliope start
+```
+
+Kalliope will load default settings and brain, the output should looks the following
+```
+Starting event manager
+Events loaded
+Starting Kalliope
+Press Ctrl+C for stopping
+Starting REST API Listening port: 5000
+```
+
+Then speak the hotwork out loud to wake up Kalliope. By default, the hotwork is "Kalliopé" with the french pronunciation.
+If the trigger is successfully raised, you'll see "say something" into the console. 
+```
+2016-12-05 20:54:21,950 :: INFO :: Keyword 1 detected at time: 2016-12-05 20:54:21
+Say something!
+```
+
+Then you can say "bonjour" and listen the Kalliope response.
+```
+Say something!
+Google Speech Recognition thinks you said Bonjour
+Order matched in the brain. Running synapse "say-hello-fr"
+Waiting for trigger detection
+```
+
+## Get a starter configuration
+We create some starter configuration that only need to be downloaded and then started. 
+Those repositories provide you a basic structure to start playing with kalliope. We recommend you to clone one of them and then go to the next section.
+
+- [French starter config](https://github.com/kalliope-project/kalliope_starter_fr)
+- [English starter config](https://github.com/kalliope-project/kalliope_starter_en)
+
+
+## Next: Create you own bot
+If everything is ok, you can start playing with Kalliope. First, take a look to the [default settings](settings.md).

Docs/installation/debian_jessie.md

@@ -1,54 +1,28 @@
-# Kalliope installation on Debian Jessie
+# Kalliope requirements for Debian Jessie
 
-## Automated install
+## Debian packages requirements
 
-Clone the project
+Edit `/etc/apt/sources.list` and check that you have `contrib` and `non-free` are enabled:
 ```
-cd
-git clone https://github.com/kalliope-project/kalliope.git
+deb http://httpredir.debian.org/debian jessie main contrib non-free
+deb-src http://httpredir.debian.org/debian jessie main contrib non-free
 ```
 
-Edit `/etc/apt/sources.list` and check that your mirror accept "non-free" package
-```
-deb http://ftp.fr.debian.org/debian/ jessie main contrib non-free
-deb-src http://ftp.fr.debian.org/debian/ jessie main contrib non-free
-```
+Install some required system libraries and softwares:
 
-Run the install script.
-```
-./kalliope/install/install_kalliope.sh
-```
-
-## Manual install
-
-To make Kalliope work, you will have to install a certain number of libraries:
 ```
 sudo apt-get update
-sudo apt-get install git python-pip python-dev libsmpeg0 libttspico-utils libsmpeg0 flac dialog libffi-dev libffi-dev libssl-dev portaudio19-dev build-essential libssl-dev libffi-dev sox libatlas3-base mplayer
-```
-
-Clone the project
-```
-git clone https://github.com/kalliope-project/kalliope.git
+sudo apt-get install git python-dev libsmpeg0 libttspico-utils libsmpeg0 flac dialog libffi-dev libffi-dev libssl-dev portaudio19-dev build-essential libssl-dev libffi-dev sox libatlas3-base mplayer
 ```
 
-Install libs
+Let's install the last release of python-pip
 ```
-sudo pip install -r install/files/python_requirements.txt
+wget https://bootstrap.pypa.io/get-pip.py
+sudo python get-pip.py
 ```
 
-## Test your env
-
-To ensure that you can record your voice, run the following command to capture audio input from your microphone
-```
-rec test.wav
-```
-
-Press CTRL-C after capturing a sample of your voice.
-
-Then play the recorded audio file
+Then, with pip, the last release of setuptools
 ```
-mplayer test.wav
+sudo pip install -U pip setuptools
 ```
 
-If everything is ok, you can start playing with Kalliope. First, take a look to the [default settings](settings.md).