One of the great things about Algorithmia is that the platform allows you to put your own work online and make it available to other developers through the API. This guide will show you how with a walk-through of making and publishing a classic “Hello World” algorithm.
Note that this example shows how to create a Python algorithm, however all the steps shown are the same in all languages. To see specific code examples in the languages we support, check out Algorithm Development Languages.
Table of Contents
- Create your First Algorithm
- Editing Your Algorithm Locally via GIT and CLI
- Editing Your Algorithm via the Web IDE
- Publish Your Algorithm
- Deleting Algorithms
Create your First Algorithm
Let’s start by creating an algorithm. First navigate to Algorithmia and click the plus sign in the navbar to open the create menu, where you’ll see the “Algorithm” option.
When you click the “Algorithm” link, you’ll see a form for creating your algorithm that we’ll fill out step by step below:
Algorithmia Account or Organization Note: If you don’t belong to an organization, skip this step and go to the next.
If you belong to an organization then you’ll see this option before Algorithmia Name. Go ahead and select which account or organization you want to create your algorithm under.
Algorithmia Name: The first thing you’ll notice in the form is the field “Algorithm Name” which will be the name of your algorithm. You’ll want to name your algorithm something descriptive based on what the algorithm does.
For example this is the beginning portion of the Language Guides which show how to create an algorithm that splits text up into words, which is called tokenizing in natural language processing. So, this example algorithm is called “Tokenize Text”, but go ahead and name your algorithm according to what your code does.
Algorithm ID: The unique AlgoURL path users will use to call your algorithm.
Language: Next you’ll pick the language of your choice.
Source Code: Because we want to make this algorithm open source and available for everyone to view the source code, we’ll choose “Open Source”.
As an incentive to promote community contributions, open source algorithms that are not charging a royalty on the Algorithmia Platform will earn 1% of the usage cost (0.01cr/sec of execution time).
Special Permissions: Next is the “Special Permissions” section that allows your algorithm to have access to the internet and allows it to call other algorithms. In this example we’ll want access to the internet and since our final algorithm will call another algorithm we want to select “Can call other algorithms” as well.
Also under Special Permissions, you can enable “CUDA/GPU”. Since our algorithm doesn’t require a GPU environment, we’ll leave this disabled.
You can find out more about algorithm permissions in the Algorithm Permissions Section. Also, consider whether your algorithm would benefit from using a Graphics Processing Unit to accelerate certain kinds of computation, such as image processing and deep learning. When “Advanced GPU” is selected, the algorithm will run on servers with GPU hardware, with specific drivers and frameworks to help algorithm developers take advantage of GPU computing. This includes nvidia drivers, CUDA support, and several of the most popular deep learning frameworks, including TensorFlow, Caffe, Theano, and Torch.
Now hit the “Create” button on the bottom lower right of the form and you’ll see this modal:
You can now clone your Algorithm (via Git) and install the CLI to edit/test locally, or you can close the modal and continue to create your algorithm in the Web IDE.
Editing your algorithm locally via GIT and CLI
The preferred way to edit and test your Algorithm’s code is to install the CLI on your local machine, clone your algorithm’s repo via Git, and use your favorite editing tools to modify the code. This gives you the benefits of using a familiar development environment, plus an easy way to test your changes locally before committing changes back to the repo and publishing a new algorithm version.
- Install the CLI:
curl -sSLf https://algorithmia.com/install.sh | sh(Windows instructions here )
- Clone your algorithm:
algo clone username/algoname
- Use your preferred editor to modify the code
- Test your algorithm:
cd algoname; algo runlocal -D [JSON FILE]
- Commit your changes:
git commit -m [commit message]; git push origin master
- Publish your changes: you can do so using the Algo Management API or via the web IDE:
If you’re using Python, you must set an environment variable:
LANGUAGE_VERSION=python3 before using
Editing your algorithm via the web IDE
If you prefer to continue creating your algorithm in the Web IDE, simply close the modal and you should see the algorithm description page for your newly created algorithm:
Notice the tabs: Run, Docs, Cost, Discussion, Manage, and Source.
The tab currently showing Run is where users can run the algorithm with the default input that you will provide during the publishing step of the algorithm or they can run their own input to test out your algorithm. Also, on this tab, you can add a short summary stating what your algorithm is and why people might be interested in it (for example how it solves a particular problem in a use case).
Docs consists of the section that you will want to show how to use your algorithm including complete information about the input types allowed and what the expected outputs will be.
Cost will be filled out automatically once you publish your algorithm and will show if you’ve chosen to charge royalites or if you’ve decided to open source your algorithm. It will also give the estimated cost so the user consuming your algorithm can see how much it will cost.
The Discussion tab shows the comments and questions from users so you can keep up to date regarding user feedback.
Under the Manage tab you can see how to clone your algorithm, see what items are checked off in the Algorithm Checklist, delete your algorithm and edit various settings of your algorithm even after you’ve created it.
Features you can edit are:
- Visibility (Open or closed source)
- Environment (CPU or GPU)
- Properties (Licensing - note that if you choose any license other than the Algorithmia Platform License, you’ll need to have the visibility set to “Open Source”).
- Managing internet accesibility from your algorithm
- Calling other algorithms from your algorithm
If you have published your algorithm and want to only make changes to the settings on the “Manage” tab, then you will still need to hit “Build” before republishing to see your new changes. Then you can hit “Publish” after your algorithm builds and go through the normal publishing workflow.
Finally click on the Source tab which will display the UI for creating your algorithm if you prefer it over the CLI.
As you can see in your algorithm editor, there is a basic algorithm stub already written that takes a string as input and returns the string “Hello” followed by the user input.
The main thing to note about the algorithm is that it’s wrapped in the apply() function.
The apply() function defines the input point of the algorithm. We use the apply() function in order to make different algorithms standardized. This makes them easily chained and helps authors think about designing their algorithms in a way that makes them easy to leverage and predictable for end users.
To run this algorithm first hit the “Build” button on the top right hand corner of the algorithm editor and then at the bottom of the page in the console you’ll see a confirmation that it has compiled and the version number of that commit. Until you have Published your algorithm, the version number will be a hash such as
4be0e18fba270e4aaa7cff20555268903f69a11b - only you will be able to call this version. After you’ve Published an algorithm, it will be given a
major.minor.revision number as described in the Versioning Documentation.
Compiling your algorithm will also save your work, but note that the first time you compile your algorithm it might take some time while subsequent compiles will be quicker.
Once you have finished editing and want to run the algorithm, click the green Build button at the top right of the editor. This will save your algorithm by committing your code to your personal git repository and will try to compile your code.
Once your algorithm has successfully complied, you can test it out by passing input though the console at the bottom of the screen. For instance, after compiling this algorithm, you can test the “Hello World” code by typing in “World” in the console:
Publish your Algorithm
Last is publishing your algorithm. The best part of hosting your model on Algorithmia is that users can access it via an API that takes only a few lines of code to use! Here is what you can set when publishing your algorithm:
On the upper right hand side of the algorithm page you’ll see a purple button Publish which will bring up a modal:
In this modal, you’ll see a Changes tab, a Sample I/O tab, and one called Versioning.
Changes shows you your commit history and release notes.
Sample I/O is where you’ll create your sample input and output for the user to try under Try the API in the Run tab. When you add a sample input, make sure to test it out with all the inputs that you accept since users will be able to test your algorithm with their own inputs.
Under the Versioning tab, you can select whether your algorithm will be for public use or private use as well as set the royalty. The algorithm can either be royalty-free or charge per-call. If you opt to have the algorithm charge a royalty, as the author, you will earn 70% of the royalty cost.
Check out Algorithm Pricing for more information on how much algorithms will cost to run.
Under Semantic Versioning you can choose which kind of release your change should fall under: Major, Minor, or Revision.
Under “Pending Changes” you’ll see any revisions you’ve made under the “Manage” tab.
If you are satisfied with your algorithm and settings, go ahead and hit publish. Congratulations, you’re an algorithm developer!
Editing Your Algorithm
Your published algorithm can be edited from the browser, where you can edit the source code, save your work, compile, and submit the algorithm to be available through the API. You can also use Git to push directly to Algorithmia from your current workflow.
Calling Other Algorithms
Because any call made from your algorithm is considered the same session as when the user calls your algorithm, you won’t need to set an API key within your algorithm code. Instead of setting the API key on the client like you would when consuming an algorithm, you can call another from inside your algorithm and pass the input like so:
This example shows an algorithm that checks the type of input passed in, and if it is a URL, will call into the Html2Text algorithm. The original caller of your algorithm will be charged for both the first algorithm call as well as the internal algorithm call. The algorithm will automatically use the credentials of the person calling your algorithm.
(Optional) Delete your Algorithm
If your algorithm has never been published, or has only been published for Private use, you have the option to delete it when it is no longer needed. To do so, go to your algorithm’s page and click on the Manage tab, then find the Delete button at the bottom.
If you have ever published your Algorithm with “Public” selected, it cannot be deleted. This is to ensure that others’ code will not break if they have written algorithms or client code which depends on your algorithm.
Now that you’ve published your first simple algorithm on the platform, you can feel empowered to add even more algorithms. You can write them from scratch, adopt and modify open source algorithms, or even chain multiple pre-existing algorithms together to make a micro service you can call with the Algorithmia API! Get inspired by checking out our Recipes.