SambaStudio CLI setup guide

This guide describes the installation and setup of the required packages for accessing the SambaStudio platform via the SambaNova API (snapi) command-line client. The installed packages will implement the following functions:

SambaNova SDK (snsdk), the SambaStudio software developer kit.
SambaNova API (snapi) , the SambaStudio command-line interface (CLI).

Follow the instructions below for your specific procedure:

User guide: macOS instructions.
User guide: Windows instructions.
Administrator guide instructions.

Requirements

A set of client modules are required to be installed on user machines using pip. PIP is a package management system used to install and manage software packages or modules written in Python. The snsdk and snapi CLI can leverage python 3.9 or 3.10 . Python 3.9 is the preferred and recommended version.

If you encounter issues using python 3.10, please duplicate the problem in python 3.9 prior to contacting SambaNova Systems Support.

User guide: macOS

This section describes the process for users to install and configure the SambaStudio CLI on macOS.

Verify Python

Verify that you have Python 3.9 or later by running the following command.

$ python3 -V

Create a virtual environment

Use the following commands to create the virtual environment.

$ python3 -m venv <virtualenv_name>
$ source <virtualenv_name>/bin/activate

Update pip

Run the following command to update pip.

$ pip3 install -U pip

Acquire the packages to install

There are two options for acquiring the packages to install:

Download the packages to your local machine from the SambaStudio Resources screen.
Obtain the path to the packages provided by your administrator from a shared central location. See your administrator for more information.

Option 1: Download the packages from the Resources screen

Follow the steps below to download the packages from the SambaStudio Resources screen.

From the help drop-down icon in the top menu bar, click on Resources to open the screen.
Click the Download SNSDK button to download the SambaNova provided snsdk package. The package will be downloaded to the location configured by your browser.
Click the Download SNAPI button to download the SambaNova provided snapi package. The package will be downloaded to the location configured by your browser.

Figure 1. Resources screen

Option 2: Obtain the path to the packages provided by your administrator

Contact your administrator to obtain the location path of the packages.

Change the directory path

Change the current path of the directory in the command line to the path of the directory where the packages were downloaded, or to the path provided by your administrator.

$ cd <path>

Install the packages

Follow the sequence below to install the SambaStudio packages.

Be sure to follow the sequence below and install the SambaNova SDK (snsdk) package prior to installing the SambaNova API (snapi) package.

SambaNova SDK (snsdk)
First you will need to install the SambaNova SDK (snsdk) using the command below.

$ pip3 install snsdk-<downloaded-release-version-name>.whl

The name of your .whl file will be dependant on the release version of the package downloaded. For example, a downloaded file named snsdk-23.2.1+rc1-py3-none-any.whl would be used in the above command, resulting in the command $ pip3 install snsdk-23.2.1+rc1-py3-none-any.whl.

SambaNova API (snapi)
After installing the SambaNova SDK (snsdk), you can then install the SambaNova API (snapi) using the command below.

$ pip3 install SambaStudio_API_Client-<downloaded-release-version-name>.whl

The name of your .whl file will be dependant on the release version of the package downloaded. For example, a downloaded file named SambaStudio_API_Client-23.2.1+rc1-py3-none-any.whl would be used in the above command, resulting in the command $ pip3 install SambaStudio_API_Client-23.2.1+rc1-py3-none-any.whl.

Verify the installed packages

Run the command below to verify the installed packages. You should see the installed packages displayed in the list.

$ pip3 list

Setup the snapi CLI

Now that the packages have been installed you will configure the snapi CLI.

Create the snapi directory

Create a snapi directory under your home directory.

$ mkdir ~/.snapi

Create config.json

Follow the steps below to create the config.json file.

Create a file named config.json under the newly created ~/.snapi directory. Include the five lines from the example below in the config.json file.
Set the HOST_NAME to your SambaStudio host name. Contact your administrator for your environment’s correct URL.
CONFIG_DIR defines the directory where the output files are being saved. You can set it to any path of your preference, or leave it as the ~/.snapi directory, as shown in the example below.

{
    "HOST_NAME": "https://<SambaStudio-hostname>",
    "CONFIG_DIR": "./",
    "DISABLE_SSL_WARNINGS": "false"
}

Make sure that HOST_NAME does not include the / character at the end of the path. An example of the correct path would be `HOST_NAME": "https://sambastudio-domain.com`".

Acquire the API key

Acquire your API Key by navigating to your host URL in a web browser. You will be directed to the SambaStudio login page. Enter your login credentials.

SambaStudio Resources screen

From the help drop-down icon in the top menu bar, click on Resources to open the screen.

Figure 2. Resources screen

Generate the API key

The SambaStudio authorization key can be used to access any of the API resources within the platform. Follow the steps below to generate a new API key.

A new API key is generated when you click on the Generate API Key button.
Your old key will be invalid when you generate a new key.
Copy the newly generated authorization keys immediately and save them in a secure location. The keys will be lost when you leave the screen.
Be sure to replace the old authorization key with the newly generated key in your scripts.

Click Generate API Key. The warning box will open explaining that generating a new API key will make your old API key invalid.
Click Generate to create your new API key. Your new key will display in the API Authorization Key field.
Click the copy icon in the API Authorization Key field to copy your new API key to your clipboard.

Be sure to save your new API key to a safe location.

Figure 3. Generate API Key

The SambaStudio platform API key and the endpoint API key have two distinct implementations.

The platform API key, described above, is used as an authorization key for authenticated access to the platform.
The endpoint API key is a unique API key generated by the platform for each endpoint. See Create and use endpoints for information about the endpoint API key.

Create the secret.txt file

Go back to your terminal and follow the steps below to create the secret.txt file.

Create a file named secret.txt under the ~/.snapi directory.
Paste the copied API key into secret.txt.
Save, and then close it.
Set permissions to chmod 600 secret.txt.

Set the default tenant

To ensure that you are assigned to the default tenant, run the snapi command below to set the tenant to default.

$ snapi config set \
 --tenant default

Test

Congratulations! You should now be able to run snapi. Do a test by running the snapi version and snapi model list commands.

$ snapi version

$ snapi model list

Ensure that your home directory on your organization’s network file system (NFS) has been created prior to running any jobs within the platform. Contact your administrator for more information.

By default, the client uses the secret.txt and config.json in your .snapi home directory. To override, set the SNAPI_CLI_CONFIG_DIR env variable pointing to your desired directory.

User guide: Windows

This section describes the process for users to install and configure the SambaStudio CLI on Windows.

Prerequisites

Note the following prerequisites before installation.

Python 3.9. is installed.
This procedure requires access to the Python Package Index (PyPI). Either the public PyPI repository or a private PyPI repository hosted in the organization premises.
Local administrator privileges are required to the drive where the virtual environment will be created. Command shell (cmd) should be run as an administrator for the installation.
If using PowerShell (PS), ensure that RemoteSigned script execution is allowed. For more information see the following Knowledge Base Article.

Create a virtual environment

After logging in as an administrator, open the command prompt and navigate to the directory where you want to create the virtual environment.
Run the following command to create a new virtual environment, where snapi-venv is the name of the virtual environment you want to create.
```
python -m venv snapi-venv
```
Run the following command to activate the virtual environment.
```
.\snapi-venv\Scripts\activate
```
This will change the command prompt to reflect that you are now working in the virtual environment. You will need to run the command above to enter the virtual environment every time.
1. Run the following command to exit the virtual environment.
  deactivate

Update pip

Run the following command to update pip.

pip3 install -U pip

Acquire the packages to install

There are two options for acquiring the packages to install:

Download the packages to your local machine from the SambaStudio Resources screen.
Obtain the path to the packages provided by your administrator from a shared central location. See your administrator for more information.

Option 1: Download the packages from the Resources screen

Follow the steps below to download the packages from the SambaStudio Resources screen.

From the help drop-down icon in the top menu bar, click on Resources to open the screen.
Click the Download SNSDK button to download the SambaNova provided snsdk package. The package will be downloaded to the location configured by your browser.
Click the Download SNAPI button to download the SambaNova provided snapi package. The package will be downloaded to the location configured by your browser.

Figure 4. Resources screen

Option 2: Obtain the path to the packages provided by your administrator

Contact your administrator to obtain the location path of the packages.

Change the directory path

Change the current path of the directory in the command line to the path of the directory where the packages were downloaded, or to the path provided by your administrator.

cd <path>

Install the packages

Follow the sequence below to install the SambaStudio packages.

Be sure to follow the sequence below and install the SambaNova SDK (snsdk) package prior to installing the SambaNova API (snapi) package.

SambaNova SDK (snsdk)
First you will need to install the SambaNova SDK (snsdk) using the command below.

pip3 install snsdk-<downloaded-release-version-name>.whl

SambaNova API (snapi)
After installing the SambaNova SDK (snsdk), you can then install the SambaNova API (snapi) using the command below.

pip3 install SambaStudio_API_Client-<downloaded-release-version-name>.whl

The name of your .whl file will be dependant on the release version of the package downloaded. For example, a downloaded file named SambaStudio_API_Client-23.2.1+rc1-py3-none-any.whl would be used in the above command, resulting in the command pip3 install SambaStudio_API_Client-23.2.1+rc1-py3-none-any.whl.

Verify the installed packages

Run the command below to verify the installed packages. You should see the installed packages displayed in the list.

pip3 list

Setup the snapi CLI

Now that the packages have been installed you will configure the snapi CLI.

Navigate to user root directory

Navigate to the user root directory by using the corresponding command for your shell.

Using Command shell (cmd):
```
cd /d %USERPROFILE%
```
Using PowerShell (PS):
```
cd ~
```

Create the snapi directory

Create a snapi directory by running the following command.

mkdir .snapi

Create config.json

Follow the steps below to create the config.json file.

Create a file named config.json under the newly created .snapi directory. Include the five lines from the example below in the config.json file.
Set the HOST_NAME to your SambaStudio host name. Contact your administrator for your environment’s correct URL.
CONFIG_DIR defines the directory where the output files are being saved. You can set it to any path of your preference, or leave it as the .snapi directory, as shown in the example below.

{
    "HOST_NAME": "https://<SambaStudio-hostname>",
    "CONFIG_DIR": ".",
    "DISABLE_SSL_WARNINGS": "false"
}

Make sure that HOST_NAME does not include the / character at the end of the path. An example of the correct path would be `HOST_NAME": "https://sambastudio-domain.com`".

Acquire the API key

Acquire your API Key by navigating to your host URL in a web browser. You will be directed to the SambaStudio login page. Enter your login credentials.

SambaStudio Resources screen

From the help drop-down icon in the top menu bar, click on Resources to open the screen.

Figure 5. Resources screen

Generate the API key

The SambaStudio authorization key can be used to access any of the API resources within the platform. Follow the steps below to generate a new API key.

A new API key is generated when you click on the Generate API Key button.
Your old key will be invalid when you generate a new key.
Copy the newly generated authorization keys immediately and save them in a secure location. The keys will be lost when you leave the screen.
Be sure to replace the old authorization key with the newly generated key in your scripts.

Click Generate API Key. The warning box will open explaining that generating a new API key will make your old API key invalid.
Click Generate to create your new API key. Your new key will display in the API Authorization Key field.
Click the copy icon in the API Authorization Key field to copy your new API key to your clipboard.

Be sure to save your new API key to a safe location.

Figure 6. Generate API Key

The SambaStudio platform API key and the endpoint API key have two distinct implementations.

The platform API key, described above, is used as an authorization key for authenticated access to the platform.
The endpoint API key is a unique API key generated by the platform for each endpoint. See Create and use endpoints for information about the endpoint API key.

Create the secret.txt file

Go back to your terminal and follow the steps below to create the secret.txt file.

Create a file named secret.txt under the .snapi directory.
Paste the copied API key into secret.txt.
Save, and then close it.
Set permissions by running the following command.
```
icacls secret.txt /reset /c /t /q
```

Set the default tenant

To ensure that you are assigned to the default tenant, run the snapi command below to set the tenant to default.

snapi config set \
--tenant default

Test

Congratulations! You should now be able to run snapi. Do a test by running the snapi version and snapi model list commands.

snapi version

snapi model list

Ensure that your home directory on your organization’s network file system (NFS) has been created prior to running any jobs within the platform. Contact your administrator for more information.

By default, the client uses the secret.txt and config.json in your .snapi home directory. To override, set the SNAPI_CLI_CONFIG_DIR env variable pointing to your desired directory.

Common error messages

Solutions to common error messages for Windows setup are described below.

Error: No matching distribution found for snsdk-<version>

Use the flag --no-build-isolation in the pip install command.
Upgrade pip by running pip install --upgrade pip.

Error: <OS Error, Permission Error>>

Make sure you have admin permissions on the installation directory.
Open the command line shell as Administrator.

Administrator guide

This section describes the process for administrators to download the packages to be deployed for user installation.

Login to your SambaStudio account

Navigate to your provisioned SambaStudio account and enter your credentials.

SambaStudio Resources screen

From the help drop-down icon in the top menu bar, click on Resources to open the screen.

Figure 7. Resources screen

Download and stage the packages

Follow the steps below to download and stage the packages.

Click the Download SNSDK button to download the SambaNova provided snsdk package. The package will be downloaded to the location configured by your browser.
Click the Download SNAPI button to download the SambaNova provided snapi package. The package will be downloaded to the location configured by your browser.
Stage the packages in a location that is accessible to all of your SambaStudio registered users.