Skip to content

Commit

Permalink
Merge pull request #156 from kalliope-project/dev
Browse files Browse the repository at this point in the history
V0.4.0
  • Loading branch information
Sispheor authored Dec 28, 2016
2 parents 665d400 + ee55b32 commit a68377d
Show file tree
Hide file tree
Showing 121 changed files with 2,380 additions and 1,797 deletions.
15 changes: 14 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,16 @@
v0.4.0 / 2016-12-28
===================
- Add resources directory (neuron, stt, tts, (trigger))
- Install community modules from git url
- Fix API (strict slashes + included brains)
- starter kits (FR - EN)
- Add support Ubuntu 14.04
- Fix neurotransmitter (multiple synapses call)
- Neurotransmitter improvements (pass arguments to called synapse)
- Split Core Neurons and Community Neurons
- update some pip dependencies
- Add Russian snowboy model for каллиопа

v0.3.0 / 2016-12-7
=================
- add unit tests for core & neurons
Expand All @@ -21,4 +34,4 @@ v0.2 / 2016-11-21
v0.1 / 2016-11-02
=================

- Initial Release
- Initial Release
128 changes: 17 additions & 111 deletions Docs/contributing.md
Original file line number Diff line number Diff line change
@@ -1,120 +1,32 @@
# Contributing

Kalliope needs the community to improve its Core features and to create new Neurons. Let's join us !
Kalliope needs the community to improve its Core features and to create new Neurons, STTs, TTSs. Let's join us !
[Here is the Todo list](https://trello.com/b/H0TecLSi/kalliopecore) if you are looking for some ideas.

## Core

The community can contribute to the Core of Kalliope by providing some new features.

#### How to contribute
**How to contribute**

1. Fork it!
2. Create your feature branch: `git checkout -b my-new-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin my-new-feature`
5. Submit a pull request :D
1. Checkout the dev branch `git checkout dev`
1. Create your feature branch: `git checkout -b my-new-feature`
1. Commit your changes: `git commit -am 'Add some feature'`
1. Push to the branch: `git push origin my-new-feature`
1. Submit a pull request in the **dev** branch

## Community module (Neuron, STT, TTS)

## Neurons
Kalliope comes with a community [installation command](kalliope_cli.md). Your can create a module in you own git repo that will be available to all Kalliope users.

Kalliope modularity is fully based on Neuron so the community can contribute by adding their own.
Neurons are independent projects so they can be developed under a github project. Anyone can clone them, place them under the neurons repository and reuse them.
See the dedicated documentation depending on the type of module you want to code.
- create a [community neuron](contributing/contribute_neuron.md)
- create a [community STT](contributing/contribute_stt.md)
- create a [community TTS](contributing/contribute_tts.md)

Creating a new Neuron must follow some rules:

##### Repository Structure
1. The Neuron repository name is in __lowercase__.
1. The Neuron repository must be added under the __neurons__ repository coming from the Core.
1. Under the Neuron repository, the Neuron has a __README.md file__ describing the Neuron following this structure:
- Neuron name:
- Synopsis: Description of the Neuron
- Options: A table of the incoming parameters managed by the Neuron.
- Return Values: A table of the returned values which can be catched by the *say_template attribute*.
- Synapses example: An example of how to use the Neuron inside a Synapse.
- Notes: Something which needs to be add.
1. Under the Neuron repository, include a __Tests repository__ to manage the test of the Neuron.


##### Code
1. Under the Neuron repository, the Neuron file name .py is also in __lowercase__.
1. The Neuron must be coded in __Python 2.7__.
1. Under the Neuron repository, include the __init__.py file which contains: *from neuron import Neuron* (/!\ respect the Case)
1. Inside the Neuron file, the Neuron Class name is in __uppercase__.
1. The Neuron __inherits from the NeuronModule__ coming from the Core.

```
from core.NeuronModule import NeuronModule
class Say(NeuronModule):
```
1. The Neuron has a constructor __init__ which is the entry point.
The constructor has a __**kwargs argument__ which is corresponding to the Dict of incoming variables:values defined either in the brain file or in the signal.
1. The Neuron must refer to its __parent structure__ in the init by calling the super of NeuronModule.
```
def __init__(self, **kwargs):
super(Say, self).__init__(**kwargs)
```
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
```
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:
- MissingParameterException: *Some Neuron parameters are missing.*
- InvalidParameterException: *Some Neuron parameters are invalid.*
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 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.
## Constraints

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
```
Expand All @@ -131,17 +43,11 @@ We recommend the usage of an IDE like [Pycharm](https://www.jetbrains.com/pychar
##### Limitations
1. The management of incoming variable from the signal order when they are __numbers or float are not efficient__. (Thanks to @thebao for pointing this out!)
1. The management of incoming variable from the signal order when they are __numbers or float are not efficient__.
- Because of the differences between the STTs outputs: some are returning word some numbers (two != 2).
- Because of the i18n, we are not able to know if a variable should be interpreted in english, french, spanish, etc ... ("two" != "deux" != "dos")
## STT, TTS, Trigger
They are managed like Neurons, you can follow the same process to develop your own !
## Share it
*Incoming*
We are maintening a list of all the Neurons available from the community, let us know
We are maintening a list of all the Neurons available from the community, let us know you've developed your own by opening [an issue](../../issues) with the link of your neuron or send a pull request to update the [neuron list](neuron_list.md) directly.
104 changes: 104 additions & 0 deletions Docs/contributing/contribute_neuron.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
# Contributing: Create a neuron

Neurons are independent projects so they can be developed under a github project. Anyone can clone them, place them under the neurons repository and reuse them.

Creating a new Neuron must follow some rules:

## Repository Structure
1. The Neuron repository name is in __lowercase__.
1. Under the Neuron repository, the Neuron has a __README.md file__ describing the Neuron following this structure. You can get a [template here](neuron_template.md):
- Neuron name:
- Installation: The CLI command used to install the neuron
- Synopsis: Description of the Neuron
- Options: A table of the incoming parameters managed by the Neuron.
- Return Values: A table of the returned values which can be catched by the *say_template attribute*.
- Synapses example: An example of how to use the Neuron inside a Synapse.
- Notes: Something which needs to be add.
1. Under the Neuron repository, include a __Tests repository__ to manage the test of the Neuron.
1. Under the neuron repository, a [dna.yml file](dna.md) must be added that contains information about the neuron. type = "neuron"
1. Under the neuron repository, a [install.yml file](installation_file.md) must be added that contains the installation process.


## Code
1. Under the Neuron repository, the Neuron file name .py is also in __lowercase__.
1. The Neuron must be coded in __Python 2.7__.
1. Under the Neuron repository, include the __init__.py file which contains: *from neuron import Neuron* (/!\ respect the Case)
1. Inside the Neuron file, the Neuron Class name is in __uppercase__.
1. The Neuron __inherits from the NeuronModule__ coming from the Core.

```
from core.NeuronModule import NeuronModule
class Say(NeuronModule):
```
1. The Neuron has a constructor __init__ which is the entry point.
The constructor has a __**kwargs argument__ which is corresponding to the Dict of incoming variables:values defined either in the brain file or in the signal.
1. The Neuron must refer to its __parent structure__ in the init by calling the super of NeuronModule.
```
def __init__(self, **kwargs):
super(Say, self).__init__(**kwargs)
```
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
```
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:
- MissingParameterException: *Some Neuron parameters are missing.*
- InvalidParameterException: *Some Neuron parameters are invalid.*
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. 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.
## Code example
Example of neuron structure
```
myneuron/
├── __init__.py
├── myneuron.py
├── dna.yml
├── install.yml
├── README.md
└── tests
├── __init__.py
└── test_myneuron.py
```
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
```
77 changes: 77 additions & 0 deletions Docs/contributing/contribute_stt.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Contributing: Create a STT

[STT](../stt.md) are independent projects so they can be developed under a github project.
Anyone can clone them and place them under the STT repository and reuse them or directly [install](../stt.md) them

Creating a new STT must follow some rules:

## Repository Structure
1. The STT repository name is in __lowercase__.
1. Under the STT repository, the STT has a __README.md file__ describing the STT following this structure. You can get a [template here](stt_template.md):
- STT name:
- Installation: The CLI command used to install the STT
- Synopsis: Description of the STT
- Options: A table of the incoming parameters managed by the STT.
- Notes: Something which needs to be add.
- Licence: The licence you want to use
1. Under the STT repository, a [dna.yml file](dna.md) must be added that contains information about the STT. type = "stt"
1. Under the STT repository, a [install.yml file](installation_file.md) must be added that contains the installation process.


## Code
1. Under the STT repository, the STT file name .py is also in __lowercase__.
1. The STT must be coded in __Python 2.7__.
1. Under the STT repository, include the __init__.py file which contains: *from stt import STT* (/!\ respect the Case)
1. Inside the STT file, the STT Class name is in __uppercase__.
1. The STT __inherits from the OrderListener__ coming from the Core.

```
from kalliope.core.OrderListener import OrderListener
class Google(OrderListener):
```
1. The STT has a constructor __init__ which is the entry point.
The constructor has an incoming callback to call once we get the text.
The constructor has a __**kwargs argument__ which is corresponding to the Dict of incoming variables:values defined either in the settings file.
1. The STT must init itself first.
1. Attach the incoming callback to the self.attribute.
1. Obtain audio from the microphone in the constructor. (Note : we mostly use the [speech_recognition library](https://pypi.python.org/pypi/SpeechRecognition/))
1. Once you get the text back, let give it to the callback
```
def __init__(self, callback=None, **kwargs):
OrderListener.__init__(self)
self.callback = callback
# -------------------
# do amazing code
# -------------------
self.callback(audio_to_text)
```
## Code example
Example of STT structure
```
mystt/
├── __init__.py
├── mystt.py
├── dna.yml
├── install.yml
└── README.md
```
Example of STT code
```
class Mystt(OrderListener):
def __init__(self, callback=None, **kwargs):
OrderListener.__init__(self)
self.callback = callback
# -------------------
# - get the microphone audio
# - do amazing code to retrieve the text
# - call the callback giving it the result text -> self.callback(audio_to_text)
# -------------------

```
Loading

0 comments on commit a68377d

Please sign in to comment.