This page is intended as a tutorial for developers wanting to contribute, or for end-users wanting to understand what exactly is happening under the hood.
What is Developer Mode and how do I use it?
Developer Mode is a feature in Scenarios that can be toggled on to view additional information. Developer Mode does not change what Elody does, it just allows you to view information that is normally kept hidden because it is relevant for developers who want to understand and/or improve Elody. It is also helpful for non-developers who are curious about what is going on in the background.
To enter or exit Developer Mode, click the button 'Enter Developer Mode' / 'Exit Developer Mode' on the left side of an active Scenario.
During the execution of a Scenario, the rules and programs generate a large number of objects. Some of these objects are messages to the user. Normally, only these message objects are displayed and the rest are kept hidden. While Developer Mode is active, the other objects will also be displayed.
Additionally, the right side of the screen will show detailed information on each of these objects when you click on them. You can also hover over or click on the objects to see arrows that indicate which other objects directly refer to them, which makes it easy to notice dependencies.
To make it easier to find the objects relevant for you, you can also set some filters on the left side of the screen. These filters determine which objects will be shown and which will be hidden while in Developer Mode.
The types of objects in a Scenario
The following kinds of objects can be viewed in Developer Mode. They are color-coded to be easier to differentiate.
The execution of a Scenario happens in discrete steps. An Event object is executed during each step. The start of each step is displayed as an object. Clicking on it allows you to see details on the step, such as which event it executes, and what the parameters at the time were.
Every Step executes an Event. The Scenario has a queue of Events that need to be executed. Any Rule, Program or Option can add new Events to the queue when it is executed. Whenever a new Step starts, it executes whatever Event comes next in the queue.
The following type of Events exist:
- default: This is what gets executed by Elody when the queue of Events is empty. Its job is to find another Event to execute next. Usually, this automatically created Event is to pick an appropriate Rule to execute or Options to display or execute.
- execute_rule: Execute a Rule. See for details on how Rules work.
- execute_option: Execute an Option. See for details on how Options work.
- present_options: Display a visual representation of one or more Options to the user, so that they can choose what to do next.
- execute_program: Execute a Program.
- mention_uncertainty: This means that Elody does not have enough information to go and and does not know what to do. It just displays a message asking for more information, then waits until the user enters more input or changes parameters.
user_command: An Event of this type is added to the queue any time the user enters text, uploads a file, or changes parameters.
'Step 0', which is created automatically when the Scenario starts, is of this type: it just initializes all the parameters that were selected by the user and performs anything else that is required at the start of the Scenario.
Note that new commands by the user are added to the queue, not executed immediately. This means the input entered by the user will wait until the currently scheduled Events have finished.
Symbols are used to symbolize meaning. They don't do anything on their own. Each Symbol has a name and a description. Some Symbols are predefined by the system, but most are created by Developers. You can see and create Symbols here. Symbols are mostly important because of their relation to Tags.
Tags are the primary way of sharing information between different Rules and Programs. All Rules as well as internal systems of Elody rely on Tags to determine what to do.
A Tag consists of:
- A Symbol. this Symbol denotes the meaning of the Tag. View the Symbol's description to find out what a Tag with that Symbol is supposed to mean.
- A numerical weight. This is optional
- A short comment. This is optional
- An arbitrary number of other objects. This can be any of the objects listed here, from Programs and Rules to Files and even other Tags. When Tags refer to other Tags, newer Tags can refer to older Tags, but not the other way around.
Because Tags can refer to other Tags and each of them has a Symbol and optionally also a weight and comment, arbitrarily complex descriptions of tasks can be formally described using Tags. Such structures of Tags are used by Rules to determine what to do, and can also be parsed by Programs.
The Symbol of a Tag determines what the Tag means and/or does.
The first character of a Symbol has a special meaning:
- If the name starts with '?', the Symbol has a special meaning to the system and Tags with it are created automatically to signify various changes and notable events. Developers are not able to create Tags with these Symbols. For example, a Tag with the Symbol '?user_input_uploaded_file' is created whenever a user uploads a file.
- If the name starts with '!', the Symbol has a special meaning to the system. Tags with this Symbol can be created by Rules and Programs to tell Elody to perform a special action. For example, Tags with the Symbol '!set_signal_weight' are used to activate Rules.
- If the name starts with '_', the Symbol was created by a developer and has no special meaning to the system, but it is marked as private. Other users are not allowed to create Tags with this Symbol or to signal it with '!set_signal_weight'.
- All other Symbols are created by developers and can be used without restriction.
All files uploaded by users are turned into File objects, and Files are used to allow Programs to communicate with each other.
Files can have arbitrary formats and can in principle be arbitrarily large (size restrictions due to hardware limitations may apply in practice).
Files are used both as input and output of Programs. Due to this, Programs may be written in different languages but they can still communicate with each other.
Rules are unable to access the contents of Files, but Programs can. Due to this, it is recommended to let Programs apply Tags to Files in order to describe metadata about the Files' format and content. This makes that information available to Rules, because they can read the Tags.
Messages are the only object that can be visible outside of Developer Mode. They are used to communicate with the user. You can also create Messages that are only visible in Developer Mode, which can be used to make relevant information available to other developers.
There are different types of Messages and they can be formatted in different ways. Some types of Messages can include forms that ask the user to enter data. When the user fills out and submits these forms, the system will create a File with the entered data along with special Tags. You will learn more about this in the examples on the following pages, and from the documentation.
Some Events, such as the execution of a Rule or a Program, also come with a display that allows you to rate the performance of that Rule or Program.
The ratings provided here will tell Elody how much these Rules and Programs can be trusted and influence whether or not they get used again in the future.
Rules are the primary means for Elody to decide what to do next. Developers can upload Rules through the lod-tools.
An Option is the possibility of doing something, encapsulated in an object. They optionally come with a visualization to explain to the user what the Option is about, and they also have an executable component which is run if they are selected for execution (either manually by the user or automatically by Elody).
Options are similar to Rules but perform a different function. While Rules are passive and shared between different Scenarios, Options are created within a Scenario and limited to it.
Programs are arbitrary programs uploaded by Developers using the lod-tools.
They are the cornerstone of how Elody solves problems. All other objects essentially exist only to figure out which Programs need to be executed with which inputs in order to solve a problem.
When a Program executes, it has information on all the objects that were created so far during the Scenario, and it can also access the contents of any Files that are given to it as input.
Programs may be written in any language and can be Turing-complete. There is no restriction on what Programs are allowed to do, although Elody will run them in a Virtual Machine to prevent harmful side effects.
Symbols, Rules and Programs are globally shared objects, independent of Scenarios. All other objects are created in Scenarios and are not shared between them.
Symbols, Rules and Programs are automatically added to a Scenario's list of objects when they are first referenced by anything in the Scenario. All other objects are added to the list when they are created.
Rules and Programs can both receive feedback from users. The rating of Rules is used by Elody for prioritization. The rating of Programs currently has no practical effect. This may change, as this platform is still under development.