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:
- The Neuron repository name is in lowercase.
- Under the Neuron repository, the Neuron has a README.md file describing the Neuron following this structure:
- 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.
- Under the Neuron repository, include a Tests repository to manage the test of the Neuron.
- Under the neuron repository, a dna.yml file must be added that contains information about the neuron. type = "neuron"
- Under the neuron repository, a install.yml file must be added that contains the installation process.
- 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.
python 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.
Python def __init__(self, **kwargs): super(Say, self).__init__(**kwargs)
You must run unit tests with success before sending a pull request. Add new tests that cover the code you want to publish.
bash cd /path/to/kalliope python -m unittest discover
(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.
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 by the use of order must interact with the languages. This allow a Neuron to by reused by anyone, speaking any language.
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
We are maintaining a list of all the Neurons available from the community, let us know you've developed your own by opening an issue with the link of your neuron or send a pull request to update the neuron list on the Kalliope's website directly.