contributing.md 4.8 KB

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

  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

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
  1. The Neuron repository name is in lowercase.
  2. The Neuron repository must be added under the neurons repository coming from the Core.
  3. 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.
  4. 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.
  2. The Neuron must be coded in Python 2.7.
  3. Under the Neuron repository, include the init.py file which contains: from neuron import Neuron (/!\ respect the Case)
  4. Inside the Neuron file, the Neuron Class name is in uppercase.
  5. The Neuron inherits from the NeuronModule coming from the Core.

    from core.NeuronModule import NeuronModule
    class Say(NeuronModule):
    
  6. 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.

  7. 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)
    
  8. 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
    
  9. (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

  10. (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.
  11. 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
  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. Only Synapse by the use of Order must interact with the languages. This allow a Neuron to by reused by anyone, speaking any language.

  2. Respect PEP 257 -- Docstring conventions. For each class or method add a description with summary, input parameter, returned parameter, type of parameter

    def my_method(my_parameter):
        """
        Description of he method
        :param my_parameter: description of he parameter
        :type my_parameter: str
        """
    
  3. Respect PEP 8 -- Style Guide for Python Code We recommend the usage of an IDE like Pycharm

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!)
    • 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