Setup

Introduction

Cobalt is a Python toolbox from BluelightAI that helps illuminate and improve AI models. It uses Topological Data Analysis (TDA) to reveal interpretable patterns in the ways a model fails or succeeds.

Why Cobalt?

The time you have to understand and fix your model’s errors is limited, expensive and hard to scale to the size of your dataset. Cobalt automates the otherwise painful step of looking for patterns in how your model is performing. Our state-of-the-art data analysis technology is designed for maximum ease of use and speed to actionable results.

Results from Cobalt

Our solution creates interpretable and actionable tables and visuals that are easy to navigate, curate and communicate using standard data science tools like Pandas and Matplotlib, as well as our interactive UI. This makes the results you get easy to interpret, share, and discuss.

Installation

We strongly recommend installing Cobalt in a Python virtual environment, using either conda or venv.

If you have not already, install conda, either from Anaconda or miniforge.

Then set up and activate a virtual environment, and install Python in it:

conda create -y --name cobalt-env
conda activate cobalt-env
conda install -y python=3.12

Now, use pip to install Cobalt.

pip install cobalt-ai

Jupyter Lab

If you have installed Cobalt in a fresh virtual environment and want to use it in a Jupyter Lab notebook (our recommended interface), you will need to install Jupyter Lab as well:

pip install jupyterlab

If you are installing Cobalt in an environment where Jupyter Lab is already installed, this step is not necessary.

Once Cobalt is installed, the next step is to configure your license.

License Registration

If you do not have a license key, you can register for a trial or noncommercial license with the built-in setup tool. (See our license terms in Licensing.) Make sure your virtual environment is activated, and then, in a notebook or Python shell, run the following:

import cobalt
cobalt.register_license()

This will first ask whether you want to register for a trial license or a noncommercial license, and then will prompt you for some basic information. Once you have provided your information, your computer will be automatically configured with your license. If you want to register another computer under your license, you can run cobalt.register_license() on the new machine and enter the same email address.

To test that everything worked correctly, make sure your virtual environment is activated, and then start Jupyter Lab with

jupyter lab

and run an example notebook from Example Notebooks. Note that some example notebooks will require installing additional packages or downloading additional data. You can also follow the Tutorial.

Note that because Cobalt relies on some custom Jupyter extensions, you will need to launch the Jupyter server from a virtual environment where Cobalt is installed for it to work correctly. Simply selecting a kernel from a virtual environment with Cobalt installed is not enough to ensure that all Cobalt functionality will be available.

License Key Authentication

If you already have a license key, you can configure your computer to use it with the setup tool. Make sure your virtual environment is activated, and then, in a notebook or Python shell, run the following:

import cobalt
cobalt.setup_license()

This will prompt you for your license key and verify that it is valid. Note that validation requires an internet connection. The license key will be stored in a configuration file in ~/.config/cobalt/, and will be used by any installation of Cobalt running in the same user account. If you need to update the license key, you can rerun the above steps.

If you need to temporarily override the saved license key, or need to set it programmatically, it can also be provided in the COBALT_LICENSE_KEY environment variable, as visible to the Python process where Cobalt is running.

Updating Cobalt

To update Cobalt to the latest version, you can always run

pip install --upgrade cobalt-ai

Dependencies

Cobalt supports Python versions 3.8 through 3.12. Version 3.13 is not currently supported. It is expected to function reasonably well in both Jupyter Notebook and Jupyter Lab; there may be unexpected problems if you attempt to use it in other notebook environments like VSCode or PyCharm. (See VSCode Usage Issues for a description of issues that you may encounter in a VSCode environment.) We recommend using Cobalt in Jupyter Lab as it by default offers more screen real estate than Jupyter Notebook.

In order to minimize conficts with user environments, we have tried to keep Cobalt’s dependencies as close as possible to the standard data science library. Dependencies include:

  • NumPy and SciPy

  • Pandas

  • matplotlib and Seaborn

  • Numba

  • pynndescent

Support

Cobalt is beta software. We welcome bug reports and feature requests.

Assistance is available from your BlueLightAI representative or by contacting support@bluelightai.com.