Python Setup — Run Locally

Running the course notebooks on your own computer

Note

Colab is the course default and needs zero setup — if you just want to follow along in class, use the Google Colab setup instead. This guide is the local alternative: a step up in involvement, but worth it if you want to keep working after the course ends or use a paid LLM API instead of Colab’s built-in Gemini. It assumes you’re comfortable with a terminal.

The notebooks are written to work both in Colab and locally. In Colab, Day 1 uses the free built-in Gemini and Day 2 reads frozen predictions (no key); from Day 3 the notebooks call the Gemini API. Run locally, every notebook that calls a model uses the Gemini API whenever GEMINI_API_KEY is set — Day 3 onward with temperature=0 + a fixed seed, so results are reproducible. Here is how to go from nothing to a running notebook.

What each day needs when you run it on your own computer:

Day	Needs
Day 1 — first LLM call	`GEMINI_API_KEY` (in Colab it needs nothing)
Day 2 · S5 — gold standard	a Google sign-in for the annotation sheet — see step 6
Day 2 · S6 — evaluation metrics	nothing; it reads frozen predictions
Day 3 — prompt design	`GEMINI_API_KEY`
Day 4 — pipeline & sampling	nothing; it calls no model

1. Install `uv`

uv is a single tool that installs Python and manages packages — it replaces pip, venv, and pyenv, so it’s the only thing you need to install.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close and reopen your terminal, then check it works: uv --version.

2. Get the course project

Download the course repository (you need git, or use the green Code → Download ZIP button on GitHub and unzip it):

git clone https://github.com/egumasa/linguistic-data-analysis-II-2026.git
cd linguistic-data-analysis-II-2026

3. Create the virtual environment

A virtual environment is a private, per-project copy of Python and its packages, so what you install for this course can’t collide with anything else on your computer. uv builds one (a .venv folder) and installs everything the notebooks need in a single command:

uv sync --group dev

4. Get an API key

From Day 3 the notebooks call the model, so you need a Gemini API key (the course standardizes on Gemini). Get a free one from Google AI Studio — see Get a free Gemini API key for details.

Then set it as an environment variable in the same terminal:

# macOS / Linux
export GEMINI_API_KEY=your-key-here

# Windows (PowerShell) — setx persists it for new terminals
setx GEMINI_API_KEY "your-key-here"

Warning

An API key is a secret — it’s tied to billing. Never paste it into a notebook cell, never commit it to git, never share it. (This project’s .gitignore already ignores a .env file if you prefer to keep keys there.)

5. Open and run the notebook

uv run jupyter lab

In the browser tab that opens, navigate to a notebook that calls the model — e.g. sources/notebooks/day3_prompt_design.ipynb — and choose Run → Run All Cells. The first cell prints which backend it chose, e.g. LLM backend: Gemini API (gemini-3.1-flash-lite, temperature=0, seed=42). Everything else — loading the gold set, the confusion matrix, the error table — works exactly as in Colab. (The Day-2 notebook needs no key; it reads frozen predictions.)

6. Reading the annotation sheet (Day 2 · S5 only)

Day 2 · S5 reads your group’s annotation sheet out of Google Sheets. In Colab this needs no setup: you are already signed in, and the notebook asks your permission with a pop-up.

On your own computer there is no signed-in account to borrow, so gspread does its own sign-in — and that needs a credentials file, created once, by following gspread’s OAuth instructions. It is the one step in the course that is genuinely easier in Colab; if you only want to get through S5, open that notebook in Colab and run the rest locally.

Troubleshooting

No LLM backend found ... — you’re running locally but no key is set. Set GEMINI_API_KEY (step 4) and restart the notebook kernel (Kernel → Restart) so it picks up the new environment variable.
Wrong model — the pinned model lives in one place (the MODEL_ID constant in the setup cell); edit it there if you need a different Gemini model.
ModuleNotFoundError — you launched Jupyter outside the project env. Always start it with uv run jupyter lab from the project folder so it uses the .venv from step 3.
Could not sign in to Google Sheets from this computer ... — Day 2 · S5 only. You have no gspread credentials file yet; see step 6, or open that notebook in Colab instead.

--- title: "Python Setup — Run Locally" subtitle: "Running the course notebooks on your own computer" toc: true --- ::: {.callout-note} **Colab is the course default and needs zero setup** — if you just want to follow along in class, use the [Google Colab setup](google-colab-setup.md) instead. This guide is the *local* alternative: a step up in involvement, but worth it if you want to keep working after the course ends or use a paid LLM API instead of Colab's built-in Gemini. It assumes you're comfortable with a terminal. ::: The notebooks are written to work **both** in Colab and locally. In Colab, Day 1 uses the free built-in Gemini and Day 2 reads frozen predictions (no key); from Day 3 the notebooks call the **Gemini API**. Run locally, every notebook that calls a model uses the Gemini API whenever `GEMINI_API_KEY` is set — Day 3 onward with `temperature=0` + a fixed seed, so results are reproducible. Here is how to go from nothing to a running notebook. What each day needs when you run it on your own computer: | Day | Needs | |---|---| | Day 1 — first LLM call | `GEMINI_API_KEY` (in Colab it needs nothing) | | Day 2 · S5 — gold standard | a Google sign-in for the annotation sheet — see step 6 | | Day 2 · S6 — evaluation metrics | nothing; it reads frozen predictions | | Day 3 — prompt design | `GEMINI_API_KEY` | | Day 4 — pipeline & sampling | nothing; it calls no model | ## 1. Install `uv` [`uv`](https://docs.astral.sh/uv/) is a single tool that installs Python *and* manages packages — it replaces `pip`, `venv`, and `pyenv`, so it's the only thing you need to install. - **macOS / Linux:** ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` - **Windows (PowerShell):** ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` Close and reopen your terminal, then check it works: `uv --version`. ## 2. Get the course project Download the course repository (you need [git](https://git-scm.com/), or use the green **Code → Download ZIP** button on GitHub and unzip it): ```bash git clone https://github.com/egumasa/linguistic-data-analysis-II-2026.git cd linguistic-data-analysis-II-2026 ``` ## 3. Create the virtual environment A **virtual environment** is a private, per-project copy of Python and its packages, so what you install for this course can't collide with anything else on your computer. `uv` builds one (a `.venv` folder) and installs everything the notebooks need in a single command: ```bash uv sync --group dev ``` ## 4. Get an API key From Day 3 the notebooks call the model, so you need a **Gemini API** key (the course standardizes on Gemini). Get a free one from [Google AI Studio](https://aistudio.google.com/apikey) — see [Get a free Gemini API key](gemini-api-key.md) for details. Then set it as an environment variable in the same terminal: ```bash # macOS / Linux export GEMINI_API_KEY=your-key-here ``` ```powershell # Windows (PowerShell) — setx persists it for new terminals setx GEMINI_API_KEY "your-key-here" ``` ::: {.callout-warning} An API key is a **secret** — it's tied to billing. Never paste it into a notebook cell, never commit it to git, never share it. (This project's `.gitignore` already ignores a `.env` file if you prefer to keep keys there.) ::: ## 5. Open and run the notebook ```bash uv run jupyter lab ``` In the browser tab that opens, navigate to a notebook that calls the model — e.g. `sources/notebooks/day3_prompt_design.ipynb` — and choose **Run → Run All Cells**. The first cell prints which backend it chose, e.g. `LLM backend: Gemini API (gemini-3.1-flash-lite, temperature=0, seed=42)`. Everything else — loading the gold set, the confusion matrix, the error table — works exactly as in Colab. (The Day-2 notebook needs no key; it reads frozen predictions.) ## 6. Reading the annotation sheet (Day 2 · S5 only) Day 2 · S5 reads your group's annotation sheet out of Google Sheets. In Colab this needs no setup: you are already signed in, and the notebook asks your permission with a pop-up. On your own computer there is no signed-in account to borrow, so `gspread` does its own sign-in — and that needs a credentials file, created once, by following [gspread's OAuth instructions](https://docs.gspread.org/en/latest/oauth2.html). It is the one step in the course that is genuinely easier in Colab; if you only want to get through S5, open that notebook in Colab and run the rest locally. ## Troubleshooting - **`No LLM backend found ...`** — you're running locally but no key is set. Set `GEMINI_API_KEY` (step 4) and restart the notebook kernel (**Kernel → Restart**) so it picks up the new environment variable. - **Wrong model** — the pinned model lives in one place (the `MODEL_ID` constant in the setup cell); edit it there if you need a different Gemini model. - **`ModuleNotFoundError`** — you launched Jupyter outside the project env. Always start it with `uv run jupyter lab` from the project folder so it uses the `.venv` from step 3. - **`Could not sign in to Google Sheets from this computer ...`** — Day 2 · S5 only. You have no `gspread` credentials file yet; see step 6, or open that notebook in Colab instead.

1. Install uv

2. Get the course project

3. Create the virtual environment

4. Get an API key

5. Open and run the notebook

6. Reading the annotation sheet (Day 2 · S5 only)

Troubleshooting

1. Install `uv`