Workshop duration (including presentation): ~2 hours
Level: basic-intermediate Python, familiarity with machine learning is helpful
This workshop explores explainability and interpretability in the context of machine learning and Large Language Models (LLMs). You will move from classic XAI techniques on traditional (black-box) models, through inherently interpretable models, to transparency concerns specific to LLMs: grounded scoped retrieval systems and reasoning transparency through prompting techniques.
| # | Lab | Topic | Time |
|---|---|---|---|
| 1 | lab1-classic-xai | Classic XAI (SHAP, LIME) on black-box models | ~20 min |
| 2 | lab2-interpretable-models | Interpretable models (transparency by design) | ~15 min |
| 3 | lab3-rag-scope-detector | Local RAG system + source attribution, inline citations, and ML scope detector | ~20 min |
| 4 | lab4-cot-prompts | Prompt engineering techniques for transparent LLMs | ~15 min |
You need Python 3.10 or later. If you're not sure whether you have it, open a terminal and run:
python --versionIf you see Python 3.10.x or higher, you're good. Otherwise, install it:
Windows:
Download the installer from python.org/downloads and run it.
Important: On the first screen of the installer, check "Add Python to PATH" before clicking Install. If you miss this, Python commands won't be found in the terminal.
Mac:
The easiest way is via Homebrew. If you don't have Homebrew yet, install it first:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"Then install Python:
brew install pythonAlternatively, download the macOS installer from python.org/downloads.
| Problem | Fix |
|---|---|
python not found after installing on Windows |
You didn't check "Add Python to PATH" — reinstall and check that box, or add Python manually to your PATH environment variable |
python runs the Windows Store on Windows |
Open Settings → Apps → Advanced app execution aliases and disable the Python aliases there |
Mac uses system Python 2.x (python --version shows 2.x) |
Use python3 instead of python in all commands below |
pip not found |
Run python -m pip install --upgrade pip (or python3 -m pip ... on Mac) |
You need an IDE that supports Jupyter notebooks. We recommend Visual Studio Code (VS Code).
Download and install it from code.visualstudio.com.
After installing VS Code, install the Jupyter extension to run .ipynb notebook files:
- Open VS Code
- Go to the Extensions view (
Ctrl+Shift+Xon Windows,Cmd+Shift+Xon Mac) - Search for Jupyter (published by Microsoft)
- Click Install
The Jupyter extension also installs the Python extension automatically if you don't already have it.
| Problem | Fix |
|---|---|
| VS Code installer doesn't launch on Windows | Right-click the installer and select Run as administrator |
| VS Code opens but the Jupyter extension can't be found | Make sure you have an internet connection; if behind a proxy, configure it under File → Preferences → Settings → proxy |
| Notebooks open but "Select Kernel" shows no options | Ensure you have Python installed (step 1) and have activated the .venv environment (step 3); then click Select Kernel → Python Environments and pick the .venv interpreter |
ipykernel not found when running a cell |
Run pip install ipykernel inside the activated .venv, then reload the kernel |
After opening the workshop repo on VSCode, run the following at the root of the repo:
Windows:
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txtMac:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtAfter activation you should see
(.venv)at the start of your terminal prompt. You need to re-run theactivatecommand each time you open a new terminal.
| Problem | Fix |
|---|---|
python -m venv fails with "No module named venv" |
Run sudo apt install python3-venv (Linux) or reinstall Python (Windows/Mac) |
.venv\Scripts\activate gives a permissions error on Windows PowerShell |
Run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser once, then retry |
pip install -r requirements.txt fails with dependency conflicts |
Make sure you are inside the virtual environment (you should see (.venv) in your prompt) |
| Packages install but can't be imported | You may have multiple Python versions; ensure you activated the .venv for this project |
For Labs 3 and 4, you need to have Ollama installed and the qwen3:0.6b model pulled:
To install it on Windows:
irm https://ollama.com/install.ps1 | iexOn Mac:
curl -fsSL https://ollama.com/install.sh | shTo pull the model (522 MB) and run it:
ollama pull qwen3:0.6b
ollama run qwen3:0.6bCheck that it has been correctly pulled by listing your installed models:
ollama list| Term | Definition |
|---|---|
| XAI | Explain 57E7 able AI (techniques to explain model predictions post-hoc) |
| IAI | Interpretable AI (models that are inherently transparent e.g. linear regression, decision tree) |
| LIME | Local Interpretable Model-agnostic Explanations (XAI technique) |
| SHAP | SHapley Additive exPlanations (feature attribution XAI technique based on game theory) |
| RAG | Retrieval-Augmented Generation (grounding LLM answers in documents retrieved by their relevance to the user query) |
| Scope detector | A classifier that decides whether a query is within the system's knowledge domain |
| CoT | Chain-of-Thought prompting (asking the model to reason step by step e.g. by providing extra guidance or few-shot examples) |
| ToT | Tree of Thoughts (extended CoT technique for exploring multiple retractable reasoning branches) |
If everything failed, don't worry! You can still follow all the Lab exercises by checking the results from a previous run we did. To do so, simply check out the project at this exact commit. Although you will sadly not be able to run your own prompts or make changes to the code, you will still be able to visualize all the Lab notebooks directly on the browser, along with the results, and answer some of the discussion questions.
Hope you enjoy the workshop, and feel free to send us your feedback!