Algorithm Environments

• Overview
• Why use a predefined environment?
• View currently available environments
  • Environments available on all clusters
  • Environments available by request
• List languages and environments and download algorithm template files
  • Overview of steps
  • Option A: using the algo CLI
    • Upgrading the algo CLI
    • Listing algorithm languages (CLI)
    • Listing algorithm environments (CLI)
    • Downloading template files (CLI)
  • Option B: Using REST requests directly
    • Listing algorithm languages (REST)
    • Listing algorithm environments (REST)
    • Downloading template files (REST)

Overview

Algorithmia supports seven languages for writing algorithms: Python, R, Java, Scala, Ruby, Rust, and JavaScript. When you create an algorithm, you must select one of these languages.

For several of these languages, we’ve also created predefined, customized algorithm runtime environments to support various ML frameworks and hardware requirements. These environments are available to both our Enterprise and Teams customers.

An algorithm environment is similar to a virtual environment that you might create outside of Algorithmia, where you might choose a specific language version and optionally install specific library packages beyond whatever comes packaged standard in your language’s base library.

Why use a predefined environment?

In an Algorithmia algorithm, you have the ability to specify external library dependencies using whatever syntax is standard for your language (e.g., in a requirements.txt file for Python). Therefore, you can technically choose a generic base algorithm environment and then build a more customized ML environment on top of that. For example, you can choose a generic Python 3.7 environment and then require PyTorch as a dependency if you’re using that specific framework.

However, we recommend not doing this, and instead choosing the appropriate predefined framework-specific algorithm environment from the matrix below, for the following reasons:

1. Our predefined environments have been optimized for fast algorithm builds at compile time, and for fast algorithm loads when algorithms are called cold. This enhances the performance of algorithms you create using custom environments relative to the approach of using a vanilla base environment and specifying your own dependencies.

2. Many of our predefined environments have built-in CUDA/GPU support and access to ML-optimized hardware such as Nvidia drivers. If your algorithm requires such specialized hardware, it’s essential to use the correct predefined runtime environment, so that it’s configured correctly from the ground up to support your model.

3. Predefined environments come with template code to make getting started easier.

The algorithm runtime environment you select should match up as closely as possible with your code dependencies, in order to provide the most streamlined development experience and the best algorithm performance. With the base environment selected, you can then add any other required dependencies in whichever way is standard for your language.

View currently available environments

Below is a list of available environments that we’ve created and that can be made available to you to upon request. Once we provide you with the requested environment, you’ll be able to install it on your cluster so that your users can select it when they create new algorithms. For steps on how to list the environments available on your cluster for each particular language, see List languages and environments and download algorithm template files.

Environments available on all clusters

The matrix below lists the algorithm environments that are currently available on every Algorithmia cluster by default. To create an algorithm with a predefined environment through the API, see Using a Predefined Language Environment.

Environments available by request

We’re always adding new optimized runtime environments to support our customers using the latest language and framework versions. Therefore, in addition to those listed above, we also have the following environments available to our Enterprise customers. If there’s a specific environment listed below that you’d like to use, or if you need a custom environment that isn’t available, please ask your customer success manager so that we can get it built and installed on your cluster.

List languages and environments and download algorithm template files

Algorithm template files provide a unified starting point for developing algorithms using a specific algorithm language and environment. This page provides instructions for how to download template files for a specific language and environment using both the algo CLI and REST requests directly. The algo CLI is recommended if you’re working at the command line, while we recommend using REST requests directly for automating your workflow.

Overview of steps

Template files are specific to each algorithm environment, and algorithm environments are specific to each algorithm language. Therefore, to download template files, you’ll first need to know what languages and environments are available on your cluster. The general steps are:

1. List the available algorithm languages on your cluster.
2. List the available environments on your cluster for a language chosen from (1).
3. Download the template files for an environment chosen from (2).

Option A: using the algo CLI

Upgrading the algo CLI

To use the CLI functionality below, you’ll need algo CLI version 1.9.0 or greater. To see what version you currently have installed, you can run pip list | grep algorithmia. If you have algorithmia<1.9.0, update by running pip install algorithmia --upgrade.

Listing algorithm languages (CLI)

To list the languages available on your cluster, run the command below, which will list the details for each language.

$ algo languages
Name                      Display Name                      
anaconda3                 Conda (Environments) - beta        
csharp-dotnet-core2       C# .NET Core 2.x+ (Environments)   
java11                    Java OpenJDK 11.0 (Environments)   
python2                   Python 2.x (Environments)          
python3                   Python 3.x (Environments)          
r36                       R 3.6.x (Environments)             
scala-2                   Scala 2.x & sbt 1.3.x (Environments)

Listing algorithm environments (CLI)

Environment IDs are unique on every cluster, so you’ll need to request the list of environments for your language of choice in order to get the ID value associated with a specific environment. To list environments, run algo environment ALGO_LANG, where ALGO_LANG is the name of your language of interest from the list above. This will print out metadata for the available environments. For example, to list Python environments, you can use:

$ algo environment python3
[
    ...,
    {
        "id": "fd980f4f-1f1c-4b2f-a128-d60b40c6567a",
        "environment_specification_id": "36fd467e-fbfe-4ea6-aa66-df3f403b7132",
        "display_name": "Python 3.8 + TensorFlow GPU 2.3",
        "description": "Python 3.8 installation with CUDA 10.1 and TensorFlow 2.3 installed",
        "created_at": "2021-06-03T19:46:29.111",
        "language": {
            "name": "python3",
            "display_name": "Python 3.x (Environments)",
            "configuration": "{\n    \"display_name\": \"Python 3.x (Environments)\",\n    \"req_files\": \[\n        \"requirements.txt\"\n    \],\n    \"artifacts\": \[\n        {\"source\":\"/home/algo/.local\", \"destination\":\"/home/algo/.local/\"},\n        {\"source\":\"/opt/algorithm\", \"destination\":\"/opt/algorithm/\"}\n    \]\n}\n"
        },
        "machine_type": "GPU"
    },
    {
        "id": "ea8f42fe-ea59-4eab-920a-09176729b4fa",
        "environment_specification_id": "c6d34b46-0851-455d-97f5-ea8fd8b70552",
        "display_name": "Python 3.7 + MXNet 1.3.1",
        "description": "Python 3.7 installation with CUDA 9.0 and MXNet 1.3.1 installed",
        "created_at": "2021-06-03T18:03:14.704",
        "language": {
            "name": "python3",
            "display_name": "Python 3.x (Environments)",
            "configuration": "{\n    \"display_name\": \"Python 3.x (Environments)\",\n    \"req_files\": \[\n        \"requirements.txt\"\n    \],\n    \"artifacts\": \[\n        {\"source\":\"/home/algo/.local\", \"destination\":\"/home/algo/.local/\"},\n        {\"source\":\"/opt/algorithm\", \"destination\":\"/opt/algorithm/\"}\n    \]\n}\n"
        },
        "machine_type": "GPU"
    },
    ...
]

Depending on your cluster, the above command might return a very long list of environments, many of which won’t be useful to you. We recommend filtering the list returned; for example, to only display environments with TensorFlow 2.x preinstalled, you can run:

$ algo environment python3 | grep -iC4 -e "tensorflow 2"

Downloading template files (CLI)

To download template files for an environment from above, use the following command, replacing ENV_SPEC_ID with an environment’s environment_specification_id value from above, and DEST with the local destination (directory path) to which to save the files (specify a dot “.” to save the template files to the current directory). The template files will be saved to the local directory specified and can now be checked in to source control for algorithm development.

$ algo template ENV_SPEC_ID DEST

Option B: Using REST requests directly

To list languages and environments programmatically, you can use REST requests and then parse the JSON directly.

Listing algorithm languages (REST)

To list the languages available on your cluster, run the command below, substituting AUTH_TOKEN with an authentication token for any account on the cluster. Either specify Simple and provide an API key or specify Bearer and provide a JSON Web Token (JWT). For example, in the code below, for -H 'Authorization: Simple|Bearer AUTH_TOKEN' you’d use one or the other of the following commands, replacing the placeholders as appropriate:

• • '-H Authorization: Simple ADMIN_API_KEY'
  • '-H Authorization: Bearer JSON_WEB_TOKEN'

REST request

$ curl https://CLUSTER_DOMAIN/v1/algorithm-environments/edge/languages \
    -H 'Authorization: Simple|Bearer AUTH_TOKEN' \
    -H 'Content-type: application/json'

REST response

[
   {
      "name":"anaconda3",
      "display_name":"Conda (Environments) - beta",
      "configuration":"{\n    \"display_name\": \"Conda (Environments) - beta\",\n    \"req_files\": \[\n        \"environment.yml\"\n    \],\n    \"artifacts\": \[\n        {\"source\":\"/home/algo/.cache\", \"destination\":\"/home/algo/.cache/\"},\n        {\"source\":\"/home/algo/anaconda_environment\", \"destination\": \"/home/algo/anaconda_environment/\"},\n        {\"source\":\"/opt/algorithm\", \"destination\":\"/opt/algorithm/\"}\n    \]\n}\n"
   },
   {
      "name":"csharp-dotnet-core2",
      "display_name":"C# .NET Core 2.x+ (Environments)",
      "configuration":"{\n    \"display_name\": \"C# .NET Core 2.x+ (Environments)\",\n    \"artifacts\": \[\n        {\"source\":\"/opt/algorithm/bin/Release/\*/\*\", \"destination\":\"/opt/algorithm/\"},\n        {\"source\":\"/opt/algorithm/resources\", \"destination\":\"/opt/algorithm/resources/\"},\n        {\"source\":\"/home/algo/.nuget\", \"destination\":\"/home/algo/.nuget/\"}\n    \]\n}\n"
   },
   {
      "name":"java11",
      "display_name":"Java OpenJDK 11.0 (Environments)",
      "configuration":"{\n    \"display_name\": \"Java OpenJDK 11.0 (Environments)\",\n    \"artifacts\": \[\n        {\"source\":\"/opt/algorithm/target/\*.jar\", \"destination\":\"/opt/algorithm/target/algorithm.jar\"},\n        {\"source\":\"/opt/algorithm/target/lib\", \"destination\":\"/opt/algorithm/target/lib/\"}\n    \]\n}\n"
   },
   {
      "name":"python2",
      "display_name":"Python 2.x (Environments)",
      "configuration":"{\n    \"display_name\": \"Python 2.x (Environments)\",\n    \"req_files\": \[\n        \"requirements.txt\"\n    \],\n    \"artifacts\": \[\n        {\"source\":\"/home/algo/.local\", \"destination\":\"/home/algo/.local/\"},\n        {\"source\":\"/opt/algorithm\", \"destination\":\"/opt/algorithm/\"}\n    \]\n}\n"
   },
   {
      "name":"python3",
      "display_name":"Python 3.x (Environments)",
      "configuration":"{\n    \"display_name\": \"Python 3.x (Environments)\",\n    \"req_files\": \[\n        \"requirements.txt\"\n    \],\n    \"artifacts\": \[\n        {\"source\":\"/home/algo/.local\", \"destination\":\"/home/algo/.local/\"},\n        {\"source\":\"/opt/algorithm\", \"destination\":\"/opt/algorithm/\"}\n    \]\n}\n"
   },
   {
      "name":"r36",
      "display_name":"R 3.6.x (Environments)",
      "configuration":"{\n    \"display_name\": \"R 3.6.x (Environments)\",\n      \"req_files\": \[\n        \"packages.txt\"\n    \],\n    \"artifacts\": \[\n      {\"source\":\"/opt/algorithm\", \"destination\":\"/opt/algorithm/\"},\n      {\"source\":\"/usr/local/lib/R/site-library\", \"destination\":\"/usr/local/lib/R/site-library/\"}\n    \]\n}\n\n"
   },
   {
      "name":"scala-2",
      "display_name":"Scala 2.x & sbt 1.3.x (Environments)",
      "configuration":"{\n    \"display_name\": \"Scala 2.x & sbt 1.3.x (Environments)\",\n    \"artifacts\": \[\n      {\"source\":\"/opt/algorithm/target/universal/stage\", \"destination\":\"/opt/algorithm/stage/\"}\n    \]\n}\n\n"
   }
]

Listing algorithm environments (REST)

Environment IDs are unique on every cluster, so you’ll need to request the list of environments for your language of choice in order to get the ID value associated with a specific environment. To list environments, run the command below, substituting ALGO_LANG with a language’s name value from the output of the command above. This will print out metadata for the available environments. The response below shows an abridged listing of python3 environments.

REST request

$ curl -X GET https://CLUSTER_DOMAIN/v1/algorithm-environments/edge/languages/ALGO_LANG/environments \
    -H 'Authorization: Simple|Bearer AUTH_TOKEN' \
    -H 'Content-type: application/json'

REST response

[
    ...,
    {
        "id": "fd980f4f-1f1c-4b2f-a128-d60b40c6567a",
        "environment_specification_id": "36fd467e-fbfe-4ea6-aa66-df3f403b7132",
        "display_name": "Python 3.8 + TensorFlow GPU 2.3",
        "description": "Python 3.8 installation with CUDA 10.1 and TensorFlow 2.3 installed",
        "created_at": "2021-06-03T19:46:29.111",
        "language": {
            "name": "python3",
            "display_name": "Python 3.x (Environments)",
            "configuration": "{\n    \"display_name\": \"Python 3.x (Environments)\",\n    \"req_files\": \[\n        \"requirements.txt\"\n    \],\n    \"artifacts\": \[\n        {\"source\":\"/home/algo/.local\", \"destination\":\"/home/algo/.local/\"},\n        {\"source\":\"/opt/algorithm\", \"destination\":\"/opt/algorithm/\"}\n    \]\n}\n"
        },
        "machine_type": "GPU"
    },
    {
        "id": "ea8f42fe-ea59-4eab-920a-09176729b4fa",
        "environment_specification_id": "c6d34b46-0851-455d-97f5-ea8fd8b70552",
        "display_name": "Python 3.7 + MXNet 1.3.1",
        "description": "Python 3.7 installation with CUDA 9.0 and MXNet 1.3.1 installed",
        "created_at": "2021-06-03T18:03:14.704",
        "language": {
            "name": "python3",
            "display_name": "Python 3.x (Environments)",
            "configuration": "{\n    \"display_name\": \"Python 3.x (Environments)\",\n    \"req_files\": \[\n        \"requirements.txt\"\n    \],\n    \"artifacts\": \[\n        {\"source\":\"/home/algo/.local\", \"destination\":\"/home/algo/.local/\"},\n        {\"source\":\"/opt/algorithm\", \"destination\":\"/opt/algorithm/\"}\n    \]\n}\n"
        },
        "machine_type": "GPU"
    },
    ...
]

Depending on your cluster, the above command might return a very long list of environments, many of which won’t be useful to you. We recommend filtering the list returned; for example, to only display environments with TensorFlow 2.x preinstalled, you can pipe the output from above as follows:

$ curl ... | grep -iC4 -e "tensorflow 2"

Downloading template files (REST)

To download template files, you can use the command below, substituting an environment_specification_id for ENV_SPEC_ID. Note that no Authorization request header is required for this endpoint. 

REST request

$ curl -X GET https://CLUSTER_DOMAIN/v1/algorithm-environments/edge/environment-specifications/ENV_SPEC_ID/template \
    -o 'template.tar'

Now, unzip the downloaded template files into a target directory DEST (you must first create this directory if it doesn’t already exist). The files can now be checked in to source control for algorithm development.

$ tar -xvf template.tar -C DEST && rm -f template.tar