• 🚀 TL;DR
• ⚡ Quick Start
• 📖 About
• 🛠️ Configuration
• 📦 Docker Users
• 🪟 Windows Users
• 🐧 Linux Users
• 🍎 macOS Users
• 🎵 Spotify Users

SARA (Smart AI Retrieval Assistant) is a demo project showcasing advanced machine learning techniques using FAISS and SBERT.

To run the demo with Docker (it will auto-download the image), execute:

docker run --rm -it rrswe/sara:latest

Note: Spotify integration isn’t included in this build. See the Spotify section for details.

Welcome to SARA, your Smart AI Retrieval Assistant—a demo project showcasing advanced machine learning techniques using transformer-based embedding models like SBERT and efficient vector-indexing methods such as FAISS to rapidly locate contextually relevant information. This guide provides step-by-step instructions for installing and running SARA. If you prefer to run the program without installing any dependencies locally, please refer to the Docker Users section. Please note that a brief delay may occur when launching the program as Python initializes the machine learning modules; this behavior is expected. For a formal project overview, refer to sara.pdf.

The demo dataset was intended to be used with Spotify integration. For privacy reasons, the Docker image does not enable Spotify; enabling this feature requires a client secret. The Spotify integration is designed to deliver the best demo experience, though it requires additional setup steps and a Premium Spotify subscription. Please note this is an optional, bonus feature and is not required to run SARA. For more details, see the Spotify Users section.

The configuration options shown below highlight the main settings used for the demo; they do not cover every available parameter. For a comprehensive overview and further customization details, refer to the configuration file config.py, which includes extensive self-documenting comments.

The default pager option pager in config.py is set to “text”. This option leverages a simple box-based interface to present search results in a clear and organized manner. The output is formatted into a neatly arranged text box that displays key information and provides sufficient context, ensuring that the results are easy to read and understand. When debug mode is enabled additional information is printed.

The fzf pager option is an optional bonus feature that enhances interaction. It requires fzf, neovim, and bat. These programs are not included in the Docker image. If you are not using Docker and wish to enable this feature, please ensure that these programs are installed on your system. Refer to their respective repositories for more information. Additionally, the default fzf options have been configured in pager.py for convenience.

If you are planning on using the default dataset configuration settings (recommended for the demo), you may skip this section. Otherwise, please review the details below to understand how to modify the dataset parameters to suit your needs. Spotify integration is not required to use the songs dataset. Indexing the data may take considerable time depending on your available resources and the size of your dataset. For this reason, the index and metadata have been provided as a convenience for the demo.

To change the dataset, update the configuration in config.py as shown below. The configuration file contains parameters that define the dataset’s location and structure. This customization helps tailor the application to your specific data. The option to change the dataset is available only in non-Docker installations, as Docker was not configured to access host data due to privacy concerns.

=spotify_enable=: bool = False
=dataset_songs=: bool = False
dataset: str = os.path.expanduser('~/path/to/your/data') 

If you plan to use a different dataset, remember to remove or comment the configuration lines below. These lines were added solely for convenience to bypass rebuilding the index and metadata for the demo dataset.

index    = =f'./data/data-8d777f38-hnsw_index.bin'=
metadata = =f'./data/=data-8d777f38-metadata.npy='

There are two methods to install and run the Docker image. The easiest way is to pull the pre-built image from Docker Hub—see the Docker Hub Image Installation section for details. Alternatively, you can build and install the image manually; refer to the Docker Manual Image Installation section for step-by-step instructions. For additional docker commands, please refer to tables Docker Cheat Sheet and Docker Hub Cheat Sheet.

If you are using macOS or Windows, it is recommended that you install Docker Desktop. For example, regarding Windows binaries, the Docker documentation states, “Binary packages on Windows include both dockerd.exe and docker.exe. On Windows, these binaries only provide the ability to run native Windows containers (not Linux containers)” [cite:@docker_binaries]. This limitation may cause issues when attempting to run Docker images built for Linux environments—such as the SARA image. Installing Docker Desktop ensures that the necessary virtualization layer is in place, allowing you to run Linux containers smoothly.

Please note: For security reasons, the Docker methods used in this demo do not permit indexing of your own data. Although other containers can be configured to access host data, this demo container is intentionally restricted to maintain a secure, self-contained environment. This limitation is designed to prevent unintended exposure of sensitive information while providing a convenient demonstration of the SARA program. Additionally, by default, the image will run as mambauser.

1. Install Docker: Ensure Docker is installed on your system and running. If not, install Docker using your package manager or from the official website docker.com.
2. Image Pull/Run: Open a Terminal and run the following command:

docker run --rm -it rrswe/sara:latest

Docker will automatically pull the image if it does not exist locally and run it.

1. Install Docker: Ensure Docker is installed and running on your system. If not, install Docker using your package manager or from the official website docker.com.
2. Integrity Verification: See Windows Users, macOS Users, or Linux Users below for operating system specific instructions.
3. Unzipping the Archive: See Windows Users, macOS Users, or Linux Users below for operating system specific instructions.
4. Build Docker Image: Open a terminal and navigate to the project root and run the following command to build the image: docker build -t sara-demo .
5. Run SARA: To run the Docker image execute: docker run --rm -it sara-demo

This section provides an overview of various Docker commands used for managing images, containers, and related resources. It serves as a quick reference guide to assist you in running SARA. Please note that this compilation is not intended to be an exhaustive guide covering every Docker feature. For a more in-depth exploration of Docker functionalities and additional commands, please refer to the official Docker Documenation.

The docker buildx build command allows you to create a multi-architecture release for both ARM and AMD platforms.

To begin, set up a Docker buildx builder. Docker buildx is an extension that enables you to build images for multiple architectures simultaneously. This ensures that your application can run on both ARM and AMD systems. Execute the following commands to create and initialize your builder:

docker buildx create --name mybuilder --use
docker buildx inspect --bootstrap

Once your builder is ready and you’re authenticated, you can build and push your image for multiple architectures. Replace <repo/name:version> with your repository and image tag. The --platform flag specifies the target architectures (linux/amd64 and linux/arm64), and the --push flag automatically uploads the built image to your Docker repository.

docker buildx build --platform linux/amd64,linux/arm64 -t <repo/name:version> --push .

This process ensures your Docker image is portable and optimized for diverse environments, making it accessible for users on both ARM (e.g., macOS) and AMD architectures.

The preferred approach for installing all dependencies is via Micromamba. Micromamba is a lightweight, statically linked version of mamba that provides a self-contained executable which, streamlines the installation process. According to its GitHub documentation, micromamba is especially recommended when a single, self-contained executable is required, which is precisely our scenario [cite:@micromamba].

1. Integrity Verification:
   • Navigate to the folder containing sara.zip and sara.zip.md5.
   • Right-click on an empty space in the folder and select “Open in Terminal.”
   • In the Terminal window, run the command: Get-FileHash sara.zip -Algorithm MD5
   • Compare the resulting MD5 hash with the contents of sara.zip.md5 to verify file integrity.
2. Unzipping the Archive:
   • Right-click on the sara.zip file and select “Extract All” then click “Extract”. Note that some of the songs have non-conventional file names, which Windows may not handle properly. The error The parameter is incorrect is fine since this is only a demo dataset.
   • When prompted on the error, check “Do this for all current items” and select “Skip”. This will extract the demo dataset while bypassing any problematic file names.
3. Setting Execution Policy for Script Execution:
   • Open Windows PowerShell as an administrator by right-clicking on the Terminal app and selecting “Run as administrator.”
   • In the elevated PowerShell window, run the command: Set-ExecutionPolicy RemoteSigned. Then choose “Yes to All” option. This command allows you to run locally created scripts. By default, Windows restricts script execution to protect your system.
   • Once you have finished using the program, you can restore the default setting by running as administrator: Set-ExecutionPolicy Restricted. Restoring the execution policy helps maintain your system’s security by preventing unauthorized scripts from running.
4. Install Micromamba:
   • For the latest installation instructions, please refer to the Micromamba Installation Guide. As of 03-18-2025, you can install Micromamba using the following command:

Invoke-Expression ((Invoke-WebRequest -Uri =https://micro.mamba.pm/install.ps1= -UseBasicParsing).Content)

When prompted to initialize answer Y. You can accept the default path by pressing Enter or change it to:

~C:\Users\your-username\AppData\Local\micromamba~

• Next, open a new terminal tab and close the old one. Install the dependencies and create the ml-win-env environment by running:

micromamba create -n ml-win-env python=3.12 python-dotenv wcwidth spotipy faiss-cpu transformers sentence-transformers -c conda-forge

Answer Y to Confirm changes.

• Then, activate the environment by running:

micromamba activate ml-win-env

Once activated, you should see (ml-win-env) on the left side of your terminal prompt. Running the command Get-Command python should confirm that Python is sourced from the Micromamba environment.

1. Run SARA: Navigate to the project directory and execute python -u main.py. Note: You may receive a warning from Hugging Face regarding symlink caching. This is expected for the demo, as on Windows symlink-based caching requires either Developer Mode to be enabled or running Python as an administrator.

Linux distributions differ in their package installation methods. The instructions provided here are specific to the system on which the project was tested—NixOS. The project includes a shell.nix file to recreate the environment.

1. Integrity Verification:
   • Open a terminal
   • Navigate to the folder containing sara.zip and sara.zip.md5.
   • Run the following command: md5sum -c sara.zip.md5. You should see an OK.
2. Unzipping the Archive:
   • Execute the command: unzip sara.zip
   • Change into the directory: cd project
3. Install Dependencies:
   • If you use the fish shell, run: nix-shell --run fish. If you wish not to use fish, simply run: nix-shell
4. Run SARA: Run: make to run the program. When finished, run: exit to return to your normal shell.

This has been tested with Python 3.12.8 in the following environment:

system: =x86_64-linux=
host os: Linux 6.13.2, NixOS, 25.05 (Warbler), 25.05beta754461.d74a2335ac9c
multi-user?: yes
sandbox: yes
version: nix-env (Nix) 2.24.12
channels(root): nixos
nixpkgs: /nix/var/nix/profiles/per-user/root/channels/nixos

The preferred approach for installing all dependencies is via Micromamba. Micromamba is a lightweight, statically linked version of mamba that provides a self-contained executable which, streamlines the installation process. According to its GitHub documentation, micromamba is especially recommended when a single, self-contained executable is required, which is precisely our scenario [cite:@micromamba].

1. Integrity Verification:
   • Open a terminal
   • Navigate to the folder containing sara.zip and sara.zip.md5.
   • Run the following command: md5sum -c sara.zip.md5. You should see an OK.
2. Unzipping the Archive:
   • Execute the command: unzip sara.zip
   • Change into the directory: cd project
3. Install Micromamba:
   • For the latest installation instructions, please refer to the Micromamba Installation Guide. The prefered method for installing micromamba on macOS is via Homebrew:

brew install micromamba

After Homebrew finishes installing, it will provide instructions for modifying your startup shell script for initialization. Advanced users can disregard these instructions and instead customize their startup script to suit their needs. For example, in a fish shell startup script (config.fish), you can automate the process by using the following configuration:

if test "$(uname -s)" = "Darwin"
    set -l default_env ml-mac-env
    # Set Mamba paths
    set -gx MAMBA_EXE "/opt/homebrew/opt/micromamba/bin/mamba"
    set -gx MAMBA_ROOT_PREFIX "/Users/username/.config/micromamba"

    # Initialize the shell hook
    eval "$($MAMBA_EXE shell hook --shell fish --root-prefix $MAMBA_ROOT_PREFIX)"

    if not micromamba env list | grep -q "$default_env"
        echo "Can't activate $default_env; it does not exist. Make sure you create it."
        echo "micromamba create -n $default_env python=3.12 ..."
    else
        # echo "micromamba $default_env activated"
        micromamba activate $default_env
    end
end

• Next,Install the dependencies and create the ml-win-env environment by running:

micromamba create -n ml-win-env python=3.12 python-dotenv wcwidth spotipy faiss-cpu transformers sentence-transformers -c conda-forge

Answer Y to Confirm changes.

• Then, open a new terminal. If you have updated your startup shell script, your environment will be automatically activated. Once activated, you should see (ml-mac-env) on the right side of your terminal prompt. Running the command which python should confirm that Python is sourced from the Micromamba environment.

1. Run SARA: In your terminal, ensure you are in the project’s root directory and execute make command to launch the program.

This section covers the Spotify integration for the demo. A Spotify Premium subscription is required to skip tracks. For privacy reasons, the Docker image does not enable Spotify; enabling this feature requires a client secret. Spotify is an optional bonus feature and is not required to run the core demo.

The spotify_enable flag in config.py controls Spotify integration. When enabled, specific tracks are played based on the top search result. If you prefer not to use Spotify integration, keep spotify_enable set to False (default) while still enabling song processing by setting dataset_songs to True (default).

In order to use Spotify, you must obtain an authentication token by creating an app on the Spotify Developer Dashboard. Populate the settings for the app as shown in Table below.

After creating your app, configure your environment by creating a file named spotify.env. This file should be placed in the directory $XDG_CONFIG_HOME/spotify. Ensure that the SPOTIFY_REDIRECT_URI in the file matches the redirect URI specified in your Spotify App Settings. The file must include all necessary configuration settings to enable use of the Spotify API. Create the file as follows:

=SPOTIFY_CLIENT_ID=your-client-id=
=SPOTIFY_CLIENT_SECRET=your-client-secret=
=SPOTIFY_REDIRECT_URI=http://localhost:8888/callback=

After completing the setup, ensure that Spotify is active in your browser or via the Spotify app before launching SARA. With Spotify running, SARA will automatically play the song corresponding to your top search result when you perform a query.