Proving the Config Before the Loop Starts

# labs/voice_loop_config.py
import json
from pathlib import Path

SAMPLE_RATE = 16000
TTS_MODEL = Path("configs/en_US-lessac-medium.onnx")
RUN_CONFIG = Path("glados/data/last_run_config.json")

def build_voice_loop_config() -> dict:
    return {
        "audio": {
            "sample_rate": SAMPLE_RATE,
            "channels": 1,
            "listen_duration": 5,
            "silence_threshold": 0.01,
        },
    }

if __name__ == "__main__":
    print(json.dumps(build_voice_loop_config(), indent=2))

$ uv run python labs/voice_loop_config.py
{
  "audio": {
    "sample_rate": 16000,
    "channels": 1,
    "listen_duration": 5,
    "silence_threshold": 0.01
  }
}

A function, not a module-level dict, and the reason is mutation. A module-level dict is one object shared by every importer, so the first caller that tweaks its copy has tweaked everyone's. A factory hands each caller a fresh one. SAMPLE_RATE stays a named constant on top of that because two separate subsystems have to agree on it, and a number that must match in two places should exist in one.

def build_voice_loop_config() -> dict:
    return {
        "stt": {
            "model_size": "base",
            "device": "cpu",
            "compute_type": "int8",
            "language": "en",
        },
        "llm": {
            "model": "llama3.2:3b",
            "max_history": 20,
        },
        "tts": {
            "model": str(TTS_MODEL),
            "sample_rate": 22050,
        },
        "audio": {
            "sample_rate": SAMPLE_RATE,
            "channels": 1,
            "listen_duration": 5,
            "silence_threshold": 0.01,
        },
    }

$ uv run python labs/voice_loop_config.py
{
  "stt": {
    "model_size": "base",
    "device": "cpu",
    "compute_type": "int8",
    "language": "en"
  },
  "llm": {
    "model": "llama3.2:3b",
    "max_history": 20
  },
  "tts": {
    "model": "configs/en_US-lessac-medium.onnx",
    "sample_rate": 22050
  },
  "audio": {
    "sample_rate": 16000,
    "channels": 1,
    "listen_duration": 5,
    "silence_threshold": 0.01
  }
}

The four sections are the four stages of a turn, in the order a turn runs them, so every knob a stage owns sits in one block. Two rates now live in the same document and neither is a typo: 16,000 is what the microphone captures and what Whisper was trained on, 22,050 is what the voice model produces. Storing the path as str(TTS_MODEL) keeps the dict JSON-serializable while letting Path build it with the right separators for your operating system.

REQUIRED_SECTIONS = ("stt", "llm", "tts", "audio")

def validate_config(cfg: dict) -> list[str]:
    errors = [f"missing config section: {name}"
              for name in REQUIRED_SECTIONS if name not in cfg]
    if errors:
        return errors

    model = Path(cfg["tts"]["model"])
    if not model.exists():
        errors.append(f"TTS model not found: {model}")
    elif not Path(f"{model}.json").exists():
        errors.append(f"TTS model card not found: {model}.json")

    audio = cfg["audio"]
    if audio["sample_rate"] != SAMPLE_RATE:
        errors.append(f"audio.sample_rate must be {SAMPLE_RATE} to match the STT model")
    if audio["listen_duration"] < 1:
        errors.append("audio.listen_duration must be at least 1 second")
    if not 0.001 <= audio["silence_threshold"] <= 0.5:
        errors.append("audio.silence_threshold must be between 0.001 and 0.5")
    if cfg["llm"]["max_history"] < 2:
        errors.append("llm.max_history must be at least 2 (one exchange)")
    return errors

$ uv run python labs/voice_loop_config.py   # before the voice model is in place
Config rejected:
  - TTS model not found: configs/en_US-lessac-medium.onnx

Two decisions are doing the work here. The section sweep runs first and returns early, so every lookup below it is safe by the time it executes; skip that and the validator crashes on exactly the malformed input it was hired to describe, which the failure box demonstrates in full. And the checks accumulate into a list instead of raising on the first one, so a run reports a missing model and a nonsense threshold together. An empty list is the unambiguous all-clear.

The bounds themselves are arguments, not decoration. The floor of 0.001 on the silence threshold rejects a value so low that room hiss reads as speech; the ceiling of 0.5 rejects one so high she ignores you unless you shout. Chapter 4's SILENCE_THRESHOLD of 0.01 sits comfortably between them. Two is the smallest history that holds a question and its answer. And the sample rate check catches the class of bug that produces no error at all: a mismatch that leaves Whisper transcribing correct audio into confident nonsense.

def save_run_config(cfg: dict, path: Path) -> Path:
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(json.dumps(cfg, indent=2))
    return path

def preflight(cfg: dict) -> None:
    errors = validate_config(cfg)
    if errors:
        print("Config rejected:")
        for error in errors:
            print(f"  - {error}")
        raise SystemExit(1)
    saved = save_run_config(cfg, RUN_CONFIG)
    print(f"Config is valid. Recorded at {saved}")

def main() -> None:
    cfg = build_voice_loop_config()
    preflight(cfg)

if __name__ == "__main__":
    main()

$ uv run python labs/voice_loop_config.py ; echo "exit=$?"
Config is valid. Recorded at glados/data/last_run_config.json
exit=0

validate_config reports and preflight decides, keeping the validator a pure function you can test with a hand-built dict. The exit code pays off later: a supervisor that restarts her on boot can tell "she refused to start" from "she started" without parsing a word of English. The saved copy answers the question that arrives three days after a strange session, when you want to know which settings were actually in effect and memory offers three plausible answers.