Setup

This page will walk you through installing the required software, setting up an environment, and installing and configuring the AI agent (Codex) we will use for this workshop series.

Special Note for Windows Users

For this workshop, you will need a working Python programming environment where you can create virtual environments and run Jupyter notebooks.

If you do not already have this set up, we recommend that Windows users use the Windows Subsystem for Linux (WSL) for the workshop. WSL lets you run a Linux environment on Windows, which is often easier for Python development.

Most Windows users should be able to install Ubuntu for WSL directly from the Microsoft Store using this link: Ubuntu/WSL. After installing it, you can start your Linux shell by searching for “Ubuntu” in the Windows search bar.

If the Microsoft Store installation does not work, follow Microsoft’s more detailed WSL installation instructions here: Install WSL.

You may also want to install Windows Terminal, which provides a nicer interface for using WSL and other command-line tools.

Download the Workshop Setup Installer

Download the workshop setup installer now, but do not run it yet. This page first walks you through computer-level setup: WSL if needed, Python, npm, Codex, and the Codex Jupyter connector.

The installer is a zip file. If you plan to unzip it from the terminal and the unzip command is not available, install it first. On Ubuntu/WSL, run sudo apt update and then sudo apt install unzip. On macOS, unzip is usually already installed; if it is missing, install the Xcode Command Line Tools with xcode-select --install.

Later, in the AI provider access section, you will use the installer to create the workshop-specific Python/Jupyter environment and Codex API key configuration.

Set Up Your Development Environment

In this section, you will check that the basic tools needed for the workshop are installed and available on your computer. You will run these checks from a terminal, which is the program we will use to type setup commands.

Start by opening a terminal for your operating system.

Mac

Open the Terminal app.

WSL/Linux

Open your Linux terminal.

• Windows users using WSL: open Ubuntu from the Windows search bar, or open Windows Terminal and choose your Ubuntu/WSL profile.

• Linux users: open your usual terminal application.

Windows users should run the commands on this page inside the Ubuntu/WSL terminal, not in PowerShell or Command Prompt.

Once your terminal is open, use the commands below to check that each required tool is installed.

Python

You will need Python 3.11 or newer.

Check your Python version with:

Mac

python3 --version

WSL/Linux

python3 --version

You should see a version number beginning with 3.11 or higher.

If Python is not installed, or if your version is older than Python 3.11, install a newer version before continuing.

Mac

Install Python from python.org or with a package manager such as Homebrew.

After installing Python, run the version check again.

WSL/Linux

Install Python inside your Linux environment. On Ubuntu/WSL, you can usually install Python with:

sudo apt update
sudo apt install python3 python3-venv python3-pip

After installing Python, run the version check again.

Python virtual environment and pip support

In addition to Python itself, you will need support for virtual environments and pip, Python’s package installer.

Check that you can create virtual environments with:

python3 -m venv --help

Check that pip is available with:

python3 -m pip --version

If both commands work, you can continue.

Mac

If venv or pip is missing, reinstall Python from python.org or use your package manager to install a complete Python distribution.

WSL/Linux

If venv or pip is missing, install them inside your Linux environment:

sudo apt update
sudo apt install python3-venv python3-pip

After installing them, run the checks again.

Node.js and npm

You will also need Node.js and npm to install Codex. npm is the package manager used to install many command-line tools written for the JavaScript ecosystem.

Check that Node.js is installed with:

node --version

Check that npm is installed with:

npm --version

If both commands print version numbers, you can continue.

Mac

If Node.js or npm is missing, install Node.js from nodejs.org or with a package manager such as Homebrew.

After installing Node.js, run the checks again.

WSL/Linux

If Node.js or npm is missing, install them inside your Linux environment. On Ubuntu/WSL, you can usually install them with:

sudo apt update
sudo apt install nodejs npm

After installing Node.js and npm, run the checks again.

Code editor

We recommend using Visual Studio Code (VS Code) as your code editor for this workshop.

VS Code gives you a convenient place to edit files, open a terminal, work with notebooks, and view the workshop files.

Mac

Install VS Code from code.visualstudio.com.

You should be able to open VS Code as an application. During the workshop, it will be useful to be able to open VS Code from the terminal. Follow these instructions to enable opening code from your terminal

After it is enabled, you should be able to open VS Code using the command

code --version

WSL/Linux

Windows users using WSL: install VS Code on Windows from code.visualstudio.com, not inside WSL.

Then install the Remote Development extension packin VS Code. This allows VS Code to open and edit files inside your Ubuntu/WSL environment.

After installing VS Code and the extension, open your Ubuntu/WSL terminal and check that VS Code can be opened from the terminal:

code --version

Later, after you download and open the workshop materials, you will be able to open the project in VS Code from inside the project folder with:

code .

Linux users: install VS Code from code.visualstudio.com or use your preferred code editor.

Install Codex

Install the Codex command-line tool with npm:

npm install -g @openai/codex

If this command fails with a permissions error, use the steps in Troubleshoot npm global installs, then run the install command again.

You will also need to install a connector for Codex and the Jupyter Lab interface:

npm install -g @zed-industries/codex-acp

If this command fails with a permissions error, use the steps in Troubleshoot npm global installs, then run the install command again.

Troubleshoot npm global installs

Codex is installed as a global npm package. On some systems, global npm installs fail because the default global install folder requires administrator permissions.

Warning

Do not run the commands in this section unless an npm install -g command fails with a permissions error. If the global install command works, skip this section.

If npm install -g fails because npm cannot write to the global install folder, configure npm to install global packages into a folder in your home directory, then try the failed install command again.

Mac

mkdir -p ~/.local
npm config set prefix ~/.local
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

WSL/Linux

mkdir -p ~/.local
npm config set prefix ~/.local
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
source ~/.profile

Then check that the codex command is available:

codex --version

If your terminal says that codex was not found, close and reopen your terminal, then try the version check again.

AI provider access

This workshop uses Codex, OpenAI’s coding agent. You will be using Codex both in the JupyterLab interface with the JupyterAI plugin and in the command line interface. Some Duke departments cover access to ChatGPT. If you are able to get ChatGPT access through Duke without paying out of pocket, please set it up through Duke Software Manager before the workshop.

If your department does not cover access, you do not need to pay for ChatGPT for this workshop unless you want to. We will also provide a workshop API key that you can use instead; skip to the workshop API key setup.

Open Codex by typing codex into your terminal.

The first time you open Codex, choose the first option, Sign in with ChatGPT. This will open a web page where you should log in to ChatGPT using your Duke NetID.

Note

If you cannot get ChatGPT access, or if access would require you to pay and you do not want to, use the workshop API key setup below.

After logging in, check your login status:

codex login status

If ChatGPT login works, you can use Codex normally.

codex exec "Reply with only: Codex is working" --skip-git-repo-check

Workshop API key setup

We will provide API keys to all workshop participants. Set up the workshop API key configuration even if ChatGPT login works for you. This gives you a backup provider if ChatGPT login is unavailable or if you run out of usage during the workshop.

After you have installed Python, npm, Codex, and the Codex Jupyter connector, use the workshop setup installer. The zip includes a README.md, a requirements.txt for testing JupyterLab and Jupyter AI, and a script that creates the workshop Codex LiteLLM configuration after you paste in your API key.

Move the downloaded zip file to the folder where you want to create your workshop setup, or retrieve it again from the terminal with curl.

curl -L 'https://github.com/AI-for-Data-Analysis/ai-for-data-analysis.github.io/raw/refs/heads/main/files/student-setup.zip' -o student-setup.zip
unzip student-setup.zip

Tip

In WSL, you can open the current Linux folder in Windows File Explorer with:

explorer.exe .

You can also open a specific path by replacing . with that path.

Then run the Codex API key setup script:

cd student-setup
python3 scripts/setup_codex_litellm.py

When prompted, paste the API key provided by the workshop instructors.

The script creates a separate Codex home directory named ~/.codex-litellm. Codex will still use your regular ~/.codex folder by default and will use ~/.codex-litellm only when you explicitly launch it that way.

Then test the workshop API key configuration:

CODEX_HOME="$HOME/.codex-litellm" codex exec "Reply with only: Codex is working" --skip-git-repo-check

Optional shortcut

A shell function is a shortcut in your terminal. The function below creates a command named litellm that runs one command with the workshop Codex configuration.

This does not permanently set CODEX_HOME. It sets CODEX_HOME only for the command you run after litellm.

Mac

cat >> ~/.zshrc <<'EOF'
litellm() {
  CODEX_HOME="$HOME/.codex-litellm" "$@"
}
EOF
source ~/.zshrc

WSL/Linux

cat >> ~/.bashrc <<'EOF'
litellm() {
  CODEX_HOME="$HOME/.codex-litellm" "$@"
}
EOF
source ~/.bashrc

After adding the function, you can test Codex with:

litellm codex exec "Reply with only: Codex is working" --skip-git-repo-check

During the workshop, use normal Codex for ChatGPT login when available. Launch commands with CODEX_HOME="$HOME/.codex-litellm" when you need the workshop API key.

Set Up the Student Installer Environment

Use the workshop setup installer to verify that your environment can run JupyterLab, Jupyter AI, and the workshop Codex API key configuration.

Create a virtual environment

The setup installer contains a requirements.txt file with the Python packages needed for the setup check. We will use a Python virtual environment for these packages.

You should execute the following commands from the student-setup folder. Create a virtual environment for the setup check:

Recommended shortcut

The installer includes a script that creates .venv, activates it inside the script, upgrades pip, and installs requirements.txt.

bash scripts/setup_python_environment.sh

After the script finishes, activate the environment in your current terminal before running more commands:

source .venv/bin/activate

If you prefer to run the steps manually, create the virtual environment with:

python3 -m venv .venv

Then activate the virtual environment:

Mac

source .venv/bin/activate

WSL/Linux

source .venv/bin/activate

After activation, you should see (.venv) at the beginning of your terminal prompt.

Install Python packages

Install the required Python packages from requirements.txt:

python -m pip install -r requirements.txt

Checklist

Before the workshop, open your terminal and run these checks to confirm your setup.

Basic system checks

python3 --version        # should show Python 3.11 or newer
python3 -m venv --help   # should show venv help text
python3 -m pip --version # should show a pip version
node --version           # should show a Node.js version
npm --version            # should show an npm version

Codex command-line checks

First check that the Codex command-line tool is installed:

codex --version          # should show a Codex version
codex-acp --help         # should show codex-acp help text

If you were able to sign in with ChatGPT, you can also test normal Codex access:

codex exec "Reply with only: Codex is working" --skip-git-repo-check # should return: Codex is working

If you cannot sign in with ChatGPT, skip that normal Codex access test and use the workshop API key test instead:

CODEX_HOME="$HOME/.codex-litellm" codex exec "Reply with only: Codex is working" --skip-git-repo-check # should return: Codex is working

If you added the optional litellm shell function, you can run the same check with:

litellm codex exec "Reply with only: Codex is working" --skip-git-repo-check # should return: Codex is working

Run from the workshop materials folder in your terminal

Move into the folder where you downloaded and unzipped the workshop materials. Replace path/to/workshop-materials with the actual path to your folder.

cd path/to/workshop-materials

Check that the expected files and folders are present.

ls                  # should show the workshop files
ls .venv            # should show the virtual environment folder contents
ls requirements.txt # should show requirements.txt

Activate the virtual environment.

source .venv/bin/activate

After activation, run these checks.

python --version        # should show Python 3.11 or newer
python -m pip --version # should show pip from the virtual environment
python -m pip check     # should show: No broken requirements found.
jupyter lab --version   # should show a JupyterLab version

Workshop Data

Download the workshop data zip and put it inside a folder named analytics-accelerator.

Use this link if you want to download the zip in your browser: student materials

After you’ve downloaded the material, move to the student-setup folder inside of your analytics-accelerator folder. Then, unzip the file.

You can alternatively use terminal commands, run:

cd ~/analytics-accelerator
cd student-setup
curl -L 'https://github.com/AI-for-Data-Analysis/ai-for-data-analysis.github.io/raw/refs/heads/main/files/seattle-public-library.zip' -o seattle-public-library.zip
unzip seattle-public-library.zip

After unzipping, you should have:

~/analytics-accelerator/student-setup/seattle-public-library/