Contributing
Kalliope needs the community to improve its Core features and to create new Neurons. Let's join us !
Core
The community can contribute to the Core of Kalliope by providing some new features.
How to contribute
- Fork it!
- Create your feature branch:
git checkout -b my-new-feature
- Commit your changes:
git commit -am 'Add some feature'
- Push to the branch:
git push origin my-new-feature
- Submit a pull request :D
Neurons
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.
Creating a new Neuron must follow some rules:
Repository Structure
- The Neuron repository name is in lowercase.
- The Neuron repository must be added under the neurons repository coming from the Core.
- 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.
- Under the Neuron repository, include a Tests repository to manage the test of the Neuron.
Code
- Under the Neuron repository, the Neuron file name .py is also in lowercase.
- The Neuron must be coded in Python 2.7.
- Under the Neuron repository, include the init.py file which contains: from neuron import Neuron (/!\ respect the Case)
- Inside the Neuron file, the Neuron Class name is in uppercase.
The Neuron inherits from the NeuronModule coming from the Core.
from core.NeuronModule import NeuronModule
class Say(NeuronModule):
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.
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)
(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
(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.
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.
Constraints
- The Neuron must (as much as possible) ensure the i18n. This means that they should not manage a specific languages inside its own logic.
Only Synapse by the use of Order must interact with the languages. This allow a Neuron to by reused by anyone, speaking any language.
Limitations
- 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!)
- 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