The following three pages demonstrate how to integrate your Programs into Elody.
This page demonstrates the technical details of uploading things and explains step-by-step how to create a Scenario Plan that does something useful.
If all you want to do is to showcase a program you wrote, this page should have all you need to know.
If you want to understand how Elody can let many programs by different developers work together, then you should also read the next two pages.
The Symbols, Rules and Programs on these three pages are uploaded by three different dummy users, to demonstrate how content from different developers can be connected. The content on this page is uploaded by tutorial_developer_demo.
In this example we assume that we already have a program that does something useful, and we want to use Elody to publish this program.
We want to end up with a link that we can give to people with which they can quickly execute the program online.
We do this by providing a link to a Scenario Plan that is configured in such a way that the program we want to demonstrate is executed right at the start of the Scenario. An example Scenario Plan demonstrating the Rules and Programs on this page can be found here. Simply click the button to start the Scenario, and a Message should appear asking you to enter parameters. You can also click this link instead to start the Scenario immediately.
This tutorial will demonstrate how to create such a Scenario Plan, so that you can send a link to it to other people.
Before you can start, make sure you have done the following:
- Register an account with this website.
- Install and configure the lod-tools.
- Optionally, install and configure the lod-executor. This is not strictly necessary, but using it makes debugging easier.
Interacting with Elody
To clear up any confusion about how you can interact with Elody:
- Clicking on the link "Try it out!" at the top of any page lets you talk to Elody directly to solve a problem. Elody will use any Rules and Programs that have been uploaded, based on their ratings.
- Starting a Scenario Plan lets you talk to Elody as well, but the plan controls which Rules and Programs Elody is going to use.
- To upload new Rules and Programs, you do not interact with this website or with Elody through the browser. Use the lod-tools instead.
For this example, we are going to need two Symbols.
You can define new Symbols directly here, or you can create a text file to define the Symbols and pass it along with your Rule in the next step. If you have many Symbols, using a separate file for them is more convenient and also allows you to easily update the descriptions of the symbols when needed, so this is recommended.
This is what our file looks like:
The tab 'original' shows the file you want to upload to create the symbols. This can be done using the following command:
lod-tools create-symbols -f "/path/to/a/file/describing/the/symbols/original.txt" -r "/path/to/a/file/describing/the/symbols/processed.txt"
The file in the tab 'processed' is the output file generated by this command.
As you can see, the file 'original' is written in a relaxed JSON format. It has the general structure of a JSON file, but missing quotation marks and commas and the like are inferred automatically and you can have linebreaks in strings.
As you can see if you follow these links, all references of the form [[program/rule/symbol:name/id]] in the descriptions of the Symbols have been turned into links. This also happens in the documentation of Rules and Programs and helps with navigating between objects.
The Symbol, Rule, Option and Program all have very similar names. This may be confusing at first, but it is actually intentional to make the relationship between these objects obvious. Pay close attention to whether the name is capitalized (Rule and Program) or not (Symbol and Option), and whether it uses hyphens (Rule and Option) or underscores (Symbol and Program). If you use this website for a while, this will quickly become intuitive.
The names of Symbols, Rules, Options and Programs follow certain conventions. Specific prefixes are used to make it immediately obvious what the role of an object is in the grand scheme of things. For example, the below Rule starts with 'Demo-' because it is used for demonstrating something and is supposed to be triggered directly by a Scenario Plan. You can read more about this in the Best Practices.
The Scenario Plan
To make testing easier, you may want to create the Scenario Plan at this point.
Doing so is easy: just go to your list of plans and click the button to create a new one.
An example plan can be found here.
The following parts of this plan are important:
- It is not marked as 'private'. Otherwise other people won't be able to use it!
- It has the Symbol demo_a_simple_timeseries_prediction set as a starting tag, and the box that says it should be signalled is ticked (otherwise the Tag will be created, but it will not activate any Rules).
- You have set yourself as trusted. This makes sure that all your Rules get executed in the Scenario, even if the Rules have not received a high enough rating, yet.
- Optionally, you may decide to tick the checkbox 'Only trust explicitly'. If you do, then only your own Rules will be executed (since you have explicitly set yourself as trusted). This has the advantage that other people's Rules won't interfere with what you want to show. However, it also means that if you want your code to rely on Programs of other people, you will either have to call them yourself or manually set all those people and/or their Rules as trusted.
Once you have a Scenario Plan, you can show it to other people by copying its URL. If you want to create a link that will execute the Scenario immediately, add the parameter '?autostart' to the URL, like so: https://elody.com/scenario/plan/3/?autostart.
You can use the Scenario Plan to test your Rules and Programs after uploading them. Just start the Scenario Plan and use Developer Mode to check if Elody correctly executes the Rules and Programs you wrote. If any Rules or Programs result in an error, the Developer Mode will show an error message.
It is heavily recommended to also create a separate Scenario Plan for development. This way, you can change your program later. Simply create a second Scenario Plan that is identical to the first except that it uses the !default_program_version Tag so that development versions are used, as in this Scenario Plan.
The Symbol demo_a_simple_timeseries_prediction defined above is used to trigger a Rule. This Rule creates an Option that is presented to the user and asks them to fill in some parameters. When the Option is selected, it runs the Program we want to demonstrate and passes the selected parameters to it.
The Rule is defined below. The tab 'Before validation' is the file that was uploaded to the server, using
lod-tools upload-rule -f "/path/to/a/file/describing/the/rule/Demo-a-simple-timeseries-prediction.txt"
The tab 'After validation' is the same Rule, but after the server has filled out any missing fields with default values.
Note that the Rule file has the same relaxed JSON format as the Symbols file. The fields called '_comment' explain what each part does.
The syntactical structure of Rules is complex. You can look at the documentation for a detailed explanation.
Additionally, if you open the page of the Rule by clicking the below link, you can look at the Rule in more detail on its own page. This includes annotations and links to other objects and to the appropriate parts of the documentation, which can help you to understand the Rule more quickly. This is also useful for debugging your own Rules.
Now that we have a way to call the Program, it is time to upload the Program itself.
As mentioned in the Rule, the name of the Program is 'Demo_a_simple_timeseries_prediction'. The below tabs show all the files the Program is composed of. Assuming these files are all in the same folder, we can upload the Program with:
lod-tools upload-program -n "The_name_of_my_program" -f "/path/to/a/folder/containing/the/program"
Note that this uploads the program as a development version, not a release version, since we did not use the '-r' option. As a a result, the program will only be available in the Scenario Plan meant for development. This makes it possible to work on your program later without changing what other users see until you are done making changes and debugging the program.
The file 'DESCRIPTION.txt' is documentation, the 'Dockerfile' and 'requirements.txt' are for Docker. The file 'app.py' contains the actual meat of the Program and is referenced by the Dockerfile. More complex Programs can of course be composed of multiple code files.
After uploading your Symbols, Rules and Programs, you can start your Scenario Plan to test things. If anything doesn't work as expected, you can use the Developer Mode to find out what the problem is.
If the error messages in the Developer Mode are not precise enough, consider using the lod-executor. With this tool, you can run all Programs of a Scenario locally.
The lod-executor creates a folder for each step involving a Program execution. Find the folder for the step where your Program fails, adapt your Program, and use this command to manually repeat the step that didn't work:
lod-tools test-program --help
You can also put print() statements in your Program, which will be put into a log file by the lod library.
Finally, don't hesitate to ask for advise on the forum!
Once you are done with debugging, don't forget to upload the program again with the '-r' option to mark it as a release version.
The program shown here can actually be called by other developers. A contributor who publishes a program with a simple demonstration rule does not need to understand the intricacies of how rules work, but if their program is good enough it can still get picked up and used by other developers anyway. Once payment is implemented, they may even end up making money that way.
A more complicated Demo- Rule can make use of programs and rules of other developers. That way you can create a demo for your code even if that code relies on other programs that you didn't write yourself.
At the end of the Program, if the user did not select the parameter use_inbuilt_visualization, the Tag demo_a_simple_timeseries_prediction_need_visualization is created. Note that this only works if the Plan has 'Only trust explicitly' unchecked, or if you explicitly list the users or their Rules you want to use as trusted. Otherwise the Rules that are supposed to react to this Symbol won't be trusted and will be ignored. The checkbox is checked in the example Scenario Plan linked above, so you need to uncheck it if you want to see what other developers have done to interact with this example Demo.
It should also be understood that the Symbol demo_a_simple_timeseries_prediction_need_visualization could be improved. Ideally, the Tags created to invoke other Rules should use Symbols that are already in use for that purpose. However, since this is the first part of the tutorial, we have no other choice but to create a new symbol because no other programs exist yet. If the programs you want to connect to already exist, you can be more proactive: check what symbols other rules are already using, and use those instead.
However, this is only an inconvenience, not a problem: As we will see later in this tutorial, it is possible to create intermediary Rules to add the missing Tags, and these intermediary Rules can even be created by other developers.