Appendix A — Appendix A: Environment Setup

This appendix is the one-time setup the whole book assumes. It takes a clean machine to a state where every chapter’s notebook runs, and it ends with a single command that verifies the claim. Follow it in order, as each step depends on the one before it.

A.1 What you need

A computer you can install software on, running Windows, macOS, or Linux. Most of the book runs on an ordinary laptop CPU.
An OpenRouter API key. OpenRouter (openrouter.ai) is one account and one API that reaches many model providers. It also speaks the OpenAI protocol, so every chapter uses the standard openai package against it. Sign up, add a few dollars of credit (the entire book’s calls cost a handful of dollars), and create a key under Keys. You will paste it into a file in step 5.
About 20 GB of free disk, mostly for the embedding model and the sample documents.
A GPU (graphics processing unit) for two chapters only. The fine-tuning chapter (16) and the speech chapter (18) want one, whereas Chapters 15, 17, 19, and 20 run on CPU, as their setup callouts note. Chapter 4 shows how to rent a GPU by the hour if you do not have one, and nothing before Chapter 16 will miss it.

A.2 Step 1: Install Miniforge

Miniforge is a small, free installer for the conda package manager. We use conda because a few chapters need non-Python pieces (a PDF engine, audio libraries, and CUDA, NVIDIA’s GPU computing toolkit) that conda handles cleanly, whereas plain pip manages only Python packages. Among the conda installers, we choose Miniforge over Anaconda because Miniforge is fully open source with no licensing strings.

Windows. Download Miniforge3-Windows-x86_64.exe from github.com/conda-forge/miniforge and run it. Choose “Just Me”, accept the default location, and leave “Add Miniforge3 to PATH” unchecked, since the “Miniforge Prompt” entry that appears in the Start Menu will serve as your terminal and avoid fights with any other Python on the machine.

Open Miniforge Prompt and confirm:

conda --version

macOS and Linux. One command downloads the right installer for your chip (Apple Silicon included). Then run it and accept the prompts, including the final “initialize” question:

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/\
Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

Close and reopen your terminal, then confirm with conda --version.

If conda is not found

On Windows, ensure you are in Miniforge Prompt, because an ordinary PowerShell window does not know about conda by default. If you must use PowerShell, conda activate is more reliable there than mamba activate. On macOS and Linux, close and reopen the terminal first. If the problem persists, run ~/miniforge3/bin/conda init and reopen once more (fish-shell users: ~/miniforge3/bin/mamba shell init --shell fish --root-prefix ~/miniforge3).

A.3 Step 2: Get the companion repository

All code, data, and notebooks live in one repository. Clone it (or download it as a zip and unpack it) and work from its root folder for everything that follows:

git clone https://git.murtaza.cc/Business-Analytics/gaba-companion.git
cd gaba-companion

The layout is small enough to hold in your head: gaba/ is the book’s shared Python package, assets/data/ holds every dataset the chapters use (gold labels included), notebooks/ has one runnable notebook per chapter, and envs/ holds the environment definitions used in the next step.

A.4 Step 3: Create the environment

From the repository root:

conda env create -f envs/gaba-core.yml
conda activate gaba-core

This takes five to ten minutes the first time and does three things at once: installs every package most chapters need, installs the book’s gaba package in editable mode so from gaba.llm import call_llm works everywhere, and registers the environment so notebook tools can find it. Two later chapters use their own environments (gaba-finetune for Chapter 16, gaba-multimodal for Chapter 18); create those from the same envs/ folder when you reach the chapters that name them, and skip them until then.

A.5 Step 4: Install VS Code

Any way of running Jupyter notebooks (documents that mix runnable code cells with text and output) works with this book, but the chapters assume nothing beyond a notebook runner, and Visual Studio Code (VS Code) is the one we recommend and the one your future workplace most likely uses. Download it from code.visualstudio.com and install with the defaults.

Then install two extensions, which is enough to run everything: open the Extensions sidebar (the four-squares icon, or Ctrl+Shift+X), search for Python (Microsoft) and Jupyter (Microsoft), and click Install on each. The Python extension includes Pylance.

A few more are conveniences you can add at any time, none of which are required by the book: Rainbow CSV (readable data files), Data Wrangler (point-and-click dataframe inspection), indent-rainbow, and an AI coding assistant of your choice, on which Appendix H has opinions.

Open the repository folder in VS Code (File, Open Folder), open any notebook from notebooks/, and click the kernel picker (the kernel is the Python environment a notebook runs its code in) in the top right of the notebook. Choose Python Environments, then gaba-core. This is the step that connects the editor to the environment from step 3, and it is the most common thing to get wrong: if a notebook greets you with ImportError: No module named gaba, the kernel picker is showing some other Python.

If gaba-core does not appear in the kernel picker

VS Code sometimes needs to be told where conda is. Open Settings, search for python.condaPath, and set it to the conda executable: on Windows C:\Users\<you>\miniforge3\Scripts\conda.exe, on macOS/Linux ~/miniforge3/bin/conda. Then reload the window.

A.6 Step 5: Add your API key

Copy the template and paste in the key you created at OpenRouter:

cp .env.example .env        # Windows: copy .env.example .env

Open .env in any editor and set the one line that matters:

OPENROUTER_API_KEY=sk-or-v1-your-actual-key

The format is strict in small ways: the file is named exactly .env, it sits in the repository root, and there are no spaces around the =. The repository’s .gitignore already excludes it, so your key cannot be committed by accident; treat it like a password anyway, because anyone holding it can spend your credit.

A.7 Step 6: Verify everything at once

python -m gaba.doctor --live

The doctor checks each layer in order: the Python version, the packages, the gaba package and its data, the key, and finally one real (fraction-of-a-cent) API call. Every line prints PASS or FAIL with the specific fix, so any broken step is identified here, at setup time, before it can interrupt a chapter. When all five lines pass, every notebook in this book will run.

[PASS] Python 3.11 (need 3.11+)
[PASS] core packages importable
[PASS] gaba package installed with its data folders
[PASS] OPENROUTER_API_KEY present in .env (sk-or-v1-...18e0)
[PASS] live API call (model said "ready", cost $0.000001)

A.8 Working through the book

Each chapter is a notebook under notebooks/, run top to bottom with the gaba-core kernel unless its setup callout names another. A chapter that needs anything unusual says so in its first callout: the model it downloads on first run and how large that download is, whether it wants a GPU, and which environment it expects. Nothing else in the toolchain should need your attention again; that is the point of doing this appendix once, properly.

When something breaks later

Three errors account for nearly everything. ImportError means the wrong kernel is selected (step 4). An authentication or 402 error means the key is missing, mistyped, or out of credit (step 5). And a download stalling on first model use is a network problem, which rerunning the cell resolves; the code itself is fine. For anything else, python -m gaba.doctor --live re-checks the whole chain in five seconds.

--- title: "Appendix A: Environment Setup" --- This appendix is the one-time setup the whole book assumes. It takes a clean machine to a state where every chapter's notebook runs, and it ends with a single command that verifies the claim. Follow it in order, as each step depends on the one before it. ## What you need - **A computer you can install software on**, running Windows, macOS, or Linux. Most of the book runs on an ordinary laptop CPU. - **An OpenRouter API key.** OpenRouter ([openrouter.ai](https://openrouter.ai)) is one account and one API that reaches many model providers. It also speaks the OpenAI protocol, so every chapter uses the standard `openai` package against it. Sign up, add a few dollars of credit (the entire book's calls cost a handful of dollars), and create a key under *Keys*. You will paste it into a file in step 5. - **About 20 GB of free disk**, mostly for the embedding model and the sample documents. - **A GPU (graphics processing unit) for two chapters only.** The fine-tuning chapter (16) and the speech chapter (18) want one, whereas Chapters 15, 17, 19, and 20 run on CPU, as their setup callouts note. Chapter 4 shows how to rent a GPU by the hour if you do not have one, and nothing before Chapter 16 will miss it. ## Step 1: Install Miniforge Miniforge is a small, free installer for the conda package manager. We use conda because a few chapters need non-Python pieces (a PDF engine, audio libraries, and CUDA, NVIDIA's GPU computing toolkit) that conda handles cleanly, whereas plain `pip` manages only Python packages. Among the conda installers, we choose Miniforge over Anaconda because Miniforge is fully open source with no licensing strings. **Windows.** Download `Miniforge3-Windows-x86_64.exe` from [github.com/conda-forge/miniforge](https://github.com/conda-forge/miniforge/releases/latest) and run it. Choose "Just Me", accept the default location, and leave "Add Miniforge3 to PATH" **unchecked**, since the "Miniforge Prompt" entry that appears in the Start Menu will serve as your terminal and avoid fights with any other Python on the machine. Open Miniforge Prompt and confirm: ```bash conda --version ``` **macOS and Linux.** One command downloads the right installer for your chip (Apple Silicon included). Then run it and accept the prompts, including the final "initialize" question: ```bash curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/\ Miniforge3-$(uname)-$(uname -m).sh" bash Miniforge3-$(uname)-$(uname -m).sh ``` Close and reopen your terminal, then confirm with `conda --version`.  ::: {.callout-note title="If conda is not found"} On Windows, ensure you are in *Miniforge Prompt*, because an ordinary PowerShell window does not know about conda by default. If you must use PowerShell, `conda activate` is more reliable there than `mamba activate`. On macOS and Linux, close and reopen the terminal first. If the problem persists, run `~/miniforge3/bin/conda init` and reopen once more (fish-shell users: `~/miniforge3/bin/mamba shell init --shell fish --root-prefix ~/miniforge3`). ::: ## Step 2: Get the companion repository All code, data, and notebooks live in one repository. Clone it (or download it as a zip and unpack it) and work from its root folder for everything that follows: ```bash git clone https://git.murtaza.cc/Business-Analytics/gaba-companion.git cd gaba-companion ``` The layout is small enough to hold in your head: `gaba/` is the book's shared Python package, `assets/data/` holds every dataset the chapters use (gold labels included), `notebooks/` has one runnable notebook per chapter, and `envs/` holds the environment definitions used in the next step. ## Step 3: Create the environment From the repository root: ```bash conda env create -f envs/gaba-core.yml conda activate gaba-core ``` This takes five to ten minutes the first time and does three things at once: installs every package most chapters need, installs the book's `gaba` package in editable mode so `from gaba.llm import call_llm` works everywhere, and registers the environment so notebook tools can find it. Two later chapters use their own environments (`gaba-finetune` for Chapter 16, `gaba-multimodal` for Chapter 18); create those from the same `envs/` folder when you reach the chapters that name them, and skip them until then. ## Step 4: Install VS Code Any way of running Jupyter notebooks (documents that mix runnable code cells with text and output) works with this book, but the chapters assume nothing beyond a notebook runner, and Visual Studio Code (VS Code) is the one we recommend and the one your future workplace most likely uses. Download it from [code.visualstudio.com](https://code.visualstudio.com) and install with the defaults. Then install two extensions, which is enough to run everything: open the Extensions sidebar (the four-squares icon, or `Ctrl+Shift+X`), search for **Python** (Microsoft) and **Jupyter** (Microsoft), and click Install on each. The Python extension includes Pylance. A few more are conveniences you can add at any time, none of which are required by the book: **Rainbow CSV** (readable data files), **Data Wrangler** (point-and-click dataframe inspection), **indent-rainbow**, and an AI coding assistant of your choice, on which Appendix H has opinions.  Open the repository folder in VS Code (*File, Open Folder*), open any notebook from `notebooks/`, and click the kernel picker (the kernel is the Python environment a notebook runs its code in) in the top right of the notebook. Choose **Python Environments**, then **gaba-core**. This is the step that connects the editor to the environment from step 3, and it is the most common thing to get wrong: if a notebook greets you with `ImportError: No module named gaba`, the kernel picker is showing some other Python.  ::: {.callout-note title="If gaba-core does not appear in the kernel picker"} VS Code sometimes needs to be told where conda is. Open Settings, search for `python.condaPath`, and set it to the conda executable: on Windows `C:\Users\<you>\miniforge3\Scripts\conda.exe`, on macOS/Linux `~/miniforge3/bin/conda`. Then reload the window. ::: ## Step 5: Add your API key Copy the template and paste in the key you created at OpenRouter: ```bash cp .env.example .env # Windows: copy .env.example .env ``` Open `.env` in any editor and set the one line that matters: ``` OPENROUTER_API_KEY=sk-or-v1-your-actual-key ``` The format is strict in small ways: the file is named exactly `.env`, it sits in the repository root, and there are no spaces around the `=`. The repository's `.gitignore` already excludes it, so your key cannot be committed by accident; treat it like a password anyway, because anyone holding it can spend your credit. ## Step 6: Verify everything at once ```bash python -m gaba.doctor --live ``` The doctor checks each layer in order: the Python version, the packages, the `gaba` package and its data, the key, and finally one real (fraction-of-a-cent) API call. Every line prints `PASS` or `FAIL` with the specific fix, so any broken step is identified here, at setup time, before it can interrupt a chapter. When all five lines pass, every notebook in this book will run. ``` [PASS] Python 3.11 (need 3.11+) [PASS] core packages importable [PASS] gaba package installed with its data folders [PASS] OPENROUTER_API_KEY present in .env (sk-or-v1-...18e0) [PASS] live API call (model said "ready", cost $0.000001) ``` ## Working through the book Each chapter is a notebook under `notebooks/`, run top to bottom with the `gaba-core` kernel unless its setup callout names another. A chapter that needs anything unusual says so in its first callout: the model it downloads on first run and how large that download is, whether it wants a GPU, and which environment it expects. Nothing else in the toolchain should need your attention again; that is the point of doing this appendix once, properly. ::: {.callout-tip title="When something breaks later"} Three errors account for nearly everything. `ImportError` means the wrong kernel is selected (step 4). An authentication or 402 error means the key is missing, mistyped, or out of credit (step 5). And a download stalling on first model use is a network problem, which rerunning the cell resolves; the code itself is fine. For anything else, `python -m gaba.doctor --live` re-checks the whole chain in five seconds. :::