Configuration Reference

This document describes all configuration options for notebook-ta.

---

File Overview

notebook-ta uses two TOML configuration files:

File	Purpose
global_config.toml	LLM provider settings, default prompts
exercises.toml	Exercise definitions and unit tests

Both files can be loaded from a local path or an https:// URL.

---

global_config.toml

[llm] — LLM Provider Settings

Key	Type	Default	Description
provider	string	"ollama"	LLM backend: "ollama" or "openai_compat"
model	string	—	Model name, or "auto" to trigger hardware-based auto-selection
base_url	string	—	API endpoint URL
api_key	string	null	API key (optional for local providers)
timeout	integer	120	Request timeout in seconds
temperature	float	0.7	Sampling temperature (0.0 = deterministic, higher = more creative)
streaming	boolean	true	Enable streaming responses

When the provider is ollama and base_url points to localhost, notebook_ta.load() checks that the Ollama server is running and starts it when necessary. It then checks the selected model and downloads it when missing. Progress is shown directly in the notebook. Remote Ollama servers are only checked and are never started or modified.

Hardware auto-detection, Ollama setup progress, and the final loaded summary are grouped in one rounded notebook-ta initialization panel with a subtle theme-friendly background.

[[llm.available_models]] — Auto-selection Candidates

Used only when model = "auto". The system selects the model with the highest min_ram_gb whose requirements are met by the detected hardware.

Key	Type	Description
name	string	Model identifier (e.g. "llama3.2:3b")
description	string	Human-readable label shown during auto-selection
min_ram_gb	float	Minimum system RAM in GB
min_vram_gb	float	Minimum GPU VRAM in GB (0 means CPU-only is fine)

[prompts] — Default Prompt Templates

Key	Type	Default	Description
on_success	string	—	Prompt when all tests pass
on_failure	string	—	Prompt when tests fail, and for all subsequent hint requests
on_no_llm	string	—	Message shown when LLM is unreachable
hint_history_length	integer	3	Max previous hint exchanges included in context

Global Unit Test Settings

Key	Type	Default	Description
unit_test_timeout	number	5.0	Maximum wall-clock seconds allowed for each configured unit test. Timed-out tests are cancelled and reported as failures.

Internationalization

Key	Type	Default	Description
language	string	"en"	Language code for notebook-facing messages and labels. Built-in languages are "en" and "fr". Unsupported values emit a log warning and fall back to English.

---

exercises.toml

Each exercise is declared under [exercises.<id>].

Exercise Fields

Key	Type	Required	Description
statement	string	❌	Exercise description passed to the LLM. May be omitted if the statement is embedded in the notebook (see Embedding statements in the notebook)
additional_info	string	❌	Any other context for the LLM
prompt_on_success	string	❌	Overrides global on_success
unit_test_timeout	number	optional	Overrides the global unit test timeout for this exercise
prompt_on_failure	string	❌	Overrides global on_failure

Note — either statement in the TOML or a <div id="<id>"> block in the notebook markdown must be provided for every exercise. If neither is present, notebook_ta.load() raises a ConfigurationError.

[[exercises.<id>.tests]] — Unit Tests

Key	Type	Description
name	string	Human-readable test name
code	string	Inline Python function source
module	string	Dotted module path for external test
function	string	Function name within the external module
student_symbols	list of strings	Symbols placed in the student_globals dictionary passed to the test. Omit when using named parameters.
export_student_globals	boolean	Export the full notebook namespace as student_globals. Defaults to false; use only when a selected symbol list cannot work.

Exactly one of code or (module + function) must be specified. student_symbols and export_student_globals are mutually exclusive.

---

Example

unit_test_timeout = 5.0
language = "en"

[llm]
provider = "ollama"
model = "auto"
base_url = "http://localhost:11434"

[[llm.available_models]]
name = "llama3.2:3b"
description = "3B model — recommended"
min_ram_gb = 8.0
min_vram_gb = 0.0

[prompts]
on_success = "The student passed all tests. Analyse the solution..."
on_failure = "The student failed tests. Provide targeted hints..."
on_no_llm = "LLM unavailable. Check your Ollama installation."
hint_history_length = 3