Elody uses objects to keep track of what is happening in a Scenario. All Rules and Programs you define can access and create these objects. This is used to communicate information between programs, to give commands to Elody, to request information from the user, and so forth.
The following types of objects exist:
Of these, 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.
A detailed description of these objects is found below.
The technical documentation for the objects can be found here.
Developer Mode is a feature of Scenarios that can be toggled on to view additional information about that Scenario in your browser. Developer Mode does not change what Elody does, it just allows you to view information that is normally kept hidden.
Developer mode is how you inspect what Elody is doing in the background. It is our equivalent to the debugger of an IDE.
To enter or exit Developer Mode, click the button 'Enter Developer Mode' / 'Exit Developer Mode' on the left side of an active Scenario. This button will only show up if you are logged in and have marked yourself as a developer in your account settings.
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 invisible. While Developer Mode is active, the other types of objects will also be displayed.
In developer mode, the right side of the screen will show additional information on an object when you select it. For any object that was created by another object, this includes a link you can click to jump to the creator object. In this way, you can select an object and quickly backtrack which Program/Option/Rule was responsible for creating it.
You can also hover over or click on the objects to see arrows that indicate which other objects directly refer to them. This makes it easier 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 by pressing the "Configure Filters" button, which will show up on the left side of the screen while you are in Developer Mode. These filters determine which objects will be shown and which will be hidden while in Developer Mode.
Try playing around with the filter settings and clicking on objects to see how the display changes. You will learn to navigate the Developer Mode to find the reasoning behind anything that Elody does, with just a few clicks.
The most informative part of the Developer Mode are the "Elody Decision Process" Messages. These are created whenever Elody has to decide what Rule or Option to execute next, and they display the reasoning behind the decision in a table.
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.
Programs are arbitrary programs uploaded by Developers using the lod-tools. They are implemented using Docker.
Programs 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.
The execution of a Scenario happens in discrete steps. 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. Each step also offers a button to show an overview of the status at the beginning of the step, which summarizes all the most important information.
Elody executes an Event on each Step. 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, Elody 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. This page explains how Rules work.
- execute_option: Execute an Option. This page explains 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.
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.
Tags are related to Symbols: Think of Symbols as classes, and of Tags as instances of those classes.
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.
This page explains how Tags are used by Rules and Options.
All files uploaded by users are turned into File objects. Elody uses files 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 tutorial for developers, and from the documentation.
Rules are the primary means for Elody to decide what to do next. Developers can upload Rules through the lod-tools.
This page explains how Rules, Options and Tags work.
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 global and shared between different Scenarios, Options are created within a Scenario and are limited to it.
This page explains how Rules, Options and Tags work.