The Startup Health Check

# glados/health_check.py
from dataclasses import dataclass

@dataclass
class CheckResult:
    name: str
    passed: bool
    message: str = ""

def probe_stt(stt) -> CheckResult:
    if stt is None:
        return CheckResult("stt", False, "No STT callable injected")
    result = stt("__probe__")
    return CheckResult("stt", True, f"OK: returned {result!r}")

print(probe_stt(lambda path: "probe ok"))
print(probe_stt(None))

$ uv run python glados/health_check.py
CheckResult(name='stt', passed=True, message="OK: returned 'probe ok'")
CheckResult(name='stt', passed=False, message='No STT callable injected')

A probe has to report which component it looked at, whether it liked what it found, and why. Returning (True, "...") would carry the same information and read as check[1] at every use site; the dataclass from chapter 2 gives those two fields names, and throws in the readable repr above for free. The None guard comes first because it is the cheapest failure and the most common one: a component that was never wired in at all.

from dataclasses import dataclass, field

@dataclass
class HealthReport:
    checks: list[CheckResult] = field(default_factory=list)

    @property
    def overall_status(self) -> bool:
        return all(c.passed for c in self.checks)

    def add(self, result: CheckResult) -> None:
        self.checks.append(result)

report = HealthReport()
report.add(CheckResult("stt", True, "ok"))
print("after stt:", report.overall_status)
report.add(CheckResult("tts", False, "missing"))
print("after tts:", report.overall_status)

$ uv run python glados/health_check.py
after stt: True
after tts: False

overall_status is a @property, not a field, and the two print lines are there to show you why. It is computed from the checks, never set on its own, so reading it after the second add gives an answer that accounts for the second add. Store it as a plain field instead and you get the classic stale-cache bug: all([]) is True, so a report built empty and filled with failures would cheerfully report a healthy system. Note also field(default_factory=list). A bare = [] default is evaluated once at class definition and shared by every instance, so two reports would quietly append into the same list.

def _probe_stt(core) -> CheckResult:
    if core.stt is None:
        return CheckResult("stt", False, "No STT callable injected")
    try:
        result = core.stt("__probe__")
        if not isinstance(result, str):
            return CheckResult("stt", False, f"Expected str, got {type(result).__name__}")
        return CheckResult("stt", True, f"OK: returned {result[:40]!r}")
    except Exception as e:
        return CheckResult("stt", False, f"Raised: {e}")

def _probe_llm(core) -> CheckResult:
    if core.llm is None:
        return CheckResult("llm", False, "No LLM callable injected")
    try:
        result = core.llm("ping", [])
        if not isinstance(result, str):
            return CheckResult("llm", False, f"Expected str, got {type(result).__name__}")
        return CheckResult("llm", True, f"OK: returned {result[:40]!r}")
    except Exception as e:
        return CheckResult("llm", False, f"Raised: {e}")

def _probe_tts(core) -> CheckResult:
    if core.tts is None:
        return CheckResult("tts", False, "No TTS callable injected")
    try:
        core.tts("__probe__")
        return CheckResult("tts", True, "OK: callable executed without error")
    except Exception as e:
        return CheckResult("tts", False, f"Raised: {e}")

def run_checks(core) -> HealthReport:
    report = HealthReport()
    report.add(_probe_stt(core))
    report.add(_probe_llm(core))
    report.add(_probe_tts(core))
    return report

def print_report(report: HealthReport) -> None:
    print("\n=== GLaDOS Health Check ===")
    for check in report.checks:
        icon = "PASS" if check.passed else "FAIL"
        print(f"  [{icon}] {check.name}: {check.message}")
    status = "ALL SYSTEMS GO" if report.overall_status else "SYSTEM NOT READY"
    print(f"\n  Status: {status}")

Three probes, one skeleton: present? runs without raising? returns the type the loop depends on? The TTS probe stops after the second question on purpose, because speech synthesis returns nothing useful; its contract is "does not explode." The broad except Exception is deliberate too. A probe's job is to record a failure, not to propagate one, and the failure box below shows what happens to a health check that forgets that. Notice that run_checks returns data and print_report does the printing: the same separation you have been holding since chapter 2, which is what will let a future dashboard read the same report the terminal does.

# glados/health_check.py — the gate and the demo
from glados.core import GladOSCore

def startup(core) -> HealthReport:
    report = run_checks(core)
    print_report(report)
    if not report.overall_status:
        failed = [c.name for c in report.checks if not c.passed]
        raise RuntimeError(f"startup blocked: {', '.join(failed)} failed the probe")
    return report

if __name__ == "__main__":
    healthy = GladOSCore(
        stt=lambda path: "probe ok",
        llm=lambda text, history: "acknowledged",
        tts=lambda text: None,
    )
    startup(healthy)

    broken = GladOSCore(stt=None, llm=lambda text, history: 42, tts=None)
    try:
        startup(broken)
    except RuntimeError as e:
        print(f"  {e}")

$ uv run python glados/health_check.py

=== GLaDOS Health Check ===
  [PASS] stt: OK: returned 'probe ok'
  [PASS] llm: OK: returned 'acknowledged'
  [PASS] tts: OK: callable executed without error

  Status: ALL SYSTEMS GO

=== GLaDOS Health Check ===
  [FAIL] stt: No STT callable injected
  [FAIL] llm: Expected str, got int
  [FAIL] tts: No TTS callable injected

  Status: SYSTEM NOT READY
  startup blocked: stt, llm, tts failed the probe

The broken core is the interesting half. Its LLM is present and runs without complaint, and it still fails, because 42 is not a string and the loop would have handed that integer to the speech engine. Injectable collaborators are what make this possible: because the core takes plain callables, a two-line lambda stands in for a three-gigabyte model, and you can exercise both the healthy and the broken path in one script that starts instantly. Call startup(core) as the first statement of your entry point and a misconfiguration costs you a printed report instead of an afternoon.