The Scoring Function

# labs/idea_scorer.py
from dataclasses import dataclass, field
from datetime import datetime


@dataclass
class Idea:
    title: str
    problem: str
    approach: str
    tags: list[str] = field(default_factory=list)
    score: float = 0.0
    created_at: str = ""

    def __post_init__(self) -> None:
        if not self.created_at:
            self.created_at = datetime.now().isoformat(timespec="seconds")


if __name__ == "__main__":
    idea = Idea(
        "Wake word latency",
        "The whole pipeline wakes for any noise in the kitchen",
        "Use a lightweight VAD model to gate the Whisper call",
        tags=["stt", "latency"],
    )
    print(f"{idea.title}: score={idea.score} tags={idea.tags}")
    print(f"captured {idea.created_at}")

$ uv run python labs/idea_scorer.py
Wake word latency: score=0.0 tags=['stt', 'latency']
captured 2026-08-19T22:41:06

Your timestamp will differ; every run in this chapter stamps the moment it happened. Six fields, and two of the choices matter. problem and approach stay separate because only one of them gets scored: the approach is the proposal, the problem is the thing you re-read in six weeks when you have forgotten what "wake word latency" meant on a Tuesday. And score defaults to 0.0 so an idea that has never been through the scorer is distinguishable from one that scored nothing.

field(default_factory=list) is the form to reach for whenever a dataclass field holds a list. Write tags: list[str] = [] and the decorator refuses to build the class at all, because a default is evaluated once when Python reads the class body, so every idea would share one list and appending a tag to one would tag them all. The factory is called once per instance instead. The empty-string default on created_at is the sentinel from chapter 25: an idea created here gets stamped, an idea rebuilt from disk arrives with its stamp already filled and __post_init__ leaves it alone.

CRITERIA = {
    "lightweight": 3.0,   # has to fit beside everything else on the Pi
    "cached": 2.5,        # never pay twice for the same answer
    "gate": 2.5,          # cheap check before an expensive stage
    "smoothing": 2.0,     # quiet hardware in a quiet house
    "local": 1.0,         # nothing leaves the building
}
MAX_SCORE = 10.0


def score_idea(idea: Idea, criteria: dict[str, float]) -> float:
    total = 0.0
    text = idea.approach.lower()
    for criterion, weight in criteria.items():
        if criterion.lower() in text:
            total += weight
    return round(min(total, MAX_SCORE), 2)


if __name__ == "__main__":
    wake_word = Idea(
        "Wake word latency",
        "The whole pipeline wakes for any noise in the kitchen",
        "Use a lightweight VAD model to gate the Whisper call",
        tags=["stt", "latency"],
    )
    servo_jitter = Idea(
        "Servo 4 jitter",
        "The right elbow buzzes at low speed",
        "Apply exponential smoothing to angle commands",
        tags=["hardware"],
    )
    for candidate in (wake_word, servo_jitter):
        print(f"{candidate.title}: {score_idea(candidate, CRITERIA)}")

$ uv run python labs/idea_scorer.py
Wake word latency: 5.5
Servo 4 jitter: 2.0

Follow the arithmetic on the first one. The approach text contains "lightweight" (3.0) and "gate" (2.5); it does not contain "cached", "smoothing" or "local", so those weights contribute nothing, and 3.0 + 2.5 = 5.5. The servo idea, whose approach is "Apply exponential smoothing to angle commands", collects 2.0 and nothing else. Both sides of the comparison get lowered so Cached and cached are one criterion.

The five keywords are the entire opinion in this program. Each one stands in for a property this build actually values, and the weight says how much: fitting the Pi's memory budget beats keeping traffic in the house, because everything already runs in the house and nothing runs if it will not fit. The weights sum to 11.0, one more than MAX_SCORE, so the cap is reachable but only by an idea that satisfies nearly everything. Set the total below the cap and min() is decoration; set it far above and every serious idea pins at 10.0 and the ranking flattens.

PUNCH_LIST = [
    Idea("Wake word latency",
         "The whole pipeline wakes for any noise in the kitchen",
         "Use a lightweight VAD model to gate the Whisper call",
         tags=["stt", "latency"]),
    Idea("Servo 4 jitter",
         "The right elbow buzzes at low speed",
         "Apply exponential smoothing to angle commands before the driver sees them",
         tags=["hardware"]),
    Idea("Cold model load",
         "The first turn after boot takes seven seconds",
         "Keep the transcription model cached in a resident process",
         tags=["stt", "startup"]),
    Idea("Repeated questions",
         "She rebuilds the same weather answer every morning",
         "Serve cached answers from a local table and gate the model call on a miss",
         tags=["llm", "latency"]),
    Idea("Hard questions",
         "The 3B model stalls on anything that needs real knowledge",
         "Send the hard ones to a hosted model and read the answer back",
         tags=["llm"]),
]


def rank(ideas: list[Idea], criteria: dict[str, float]) -> list[Idea]:
    for idea in ideas:
        idea.score = score_idea(idea, criteria)
    return sorted(ideas, key=lambda i: i.score, reverse=True)


if __name__ == "__main__":
    for position, idea in enumerate(rank(PUNCH_LIST, CRITERIA), start=1):
        print(f"{position}. {idea.score:>4}  {idea.title:<20} {idea.tags}")

$ uv run python labs/idea_scorer.py
1.  6.0  Repeated questions   ['llm', 'latency']
2.  5.5  Wake word latency    ['stt', 'latency']
3.  2.5  Cold model load      ['stt', 'startup']
4.  2.0  Servo 4 jitter       ['hardware']
5.  0.0  Hard questions       ['llm']

The weekend has two slots and the list just filled them. Read the bottom of it as carefully as the top: "Hard questions" scores 0.0, and that zero is a full sentence. The idea proposes sending your household's questions to somebody else's machine, and the criteria were written by someone who will not do that, so it collects none of the five weights. Nobody had to argue with it. The yardstick had already answered, back when it was five keywords in a dict and there were no candidates in the room to defend.

rank mutates each idea's score and returns a new sorted list, so the objects carry their own result and the ordering stays a separate thing you can recompute. sorted is stable, so two ideas tied at 2.5 come back in the order they were listed, not in an order that shuffles between runs. That stability is what lets you diff two rankings and read the difference as a decision instead of noise.

# labs/idea_scorer.py — full file
import json
from dataclasses import asdict, dataclass, field
from datetime import datetime
from pathlib import Path

RESULTS_PATH = Path("glados/data/scored_ideas.json")
MAX_SCORE = 10.0

CRITERIA = {
    "lightweight": 3.0,
    "cached": 2.5,
    "gate": 2.5,
    "smoothing": 2.0,
    "local": 1.0,
}


@dataclass
class Idea:
    title: str
    problem: str
    approach: str
    tags: list[str] = field(default_factory=list)
    score: float = 0.0
    created_at: str = ""

    def __post_init__(self) -> None:
        if not self.created_at:
            self.created_at = datetime.now().isoformat(timespec="seconds")


PUNCH_LIST = [
    Idea("Wake word latency",
         "The whole pipeline wakes for any noise in the kitchen",
         "Use a lightweight VAD model to gate the Whisper call",
         tags=["stt", "latency"]),
    Idea("Servo 4 jitter",
         "The right elbow buzzes at low speed",
         "Apply exponential smoothing to angle commands before the driver sees them",
         tags=["hardware"]),
    Idea("Cold model load",
         "The first turn after boot takes seven seconds",
         "Keep the transcription model cached in a resident process",
         tags=["stt", "startup"]),
    Idea("Repeated questions",
         "She rebuilds the same weather answer every morning",
         "Serve cached answers from a local table and gate the model call on a miss",
         tags=["llm", "latency"]),
    Idea("Hard questions",
         "The 3B model stalls on anything that needs real knowledge",
         "Send the hard ones to a hosted model and read the answer back",
         tags=["llm"]),
]


def score_idea(idea: Idea, criteria: dict[str, float]) -> float:
    total = 0.0
    text = idea.approach.lower()
    for criterion, weight in criteria.items():
        if criterion.lower() in text:
            total += weight
    return round(min(total, MAX_SCORE), 2)


def rank(ideas: list[Idea], criteria: dict[str, float]) -> list[Idea]:
    for idea in ideas:
        idea.score = score_idea(idea, criteria)
    return sorted(ideas, key=lambda i: i.score, reverse=True)


def save_ranking(ideas: list[Idea], criteria: dict[str, float], path: Path) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    payload = {
        "scored_at": datetime.now().isoformat(timespec="seconds"),
        "criteria": criteria,
        "ideas": [asdict(i) for i in ideas],
    }
    path.write_text(json.dumps(payload, indent=2))


def load_ranking(path: Path) -> tuple[list[Idea], dict[str, float]]:
    payload = json.loads(path.read_text())
    return [Idea(**record) for record in payload["ideas"]], payload["criteria"]


def main() -> None:
    ideas = load_ranking(RESULTS_PATH)[0] if RESULTS_PATH.exists() else list(PUNCH_LIST)
    ranked = rank(ideas, CRITERIA)
    save_ranking(ranked, CRITERIA, RESULTS_PATH)
    reloaded, criteria = load_ranking(RESULTS_PATH)
    print(f"{len(ranked)} ideas scored against {len(criteria)} criteria")
    print(f"top: {reloaded[0].title} ({reloaded[0].score}), first written {reloaded[0].created_at}")


if __name__ == "__main__":
    main()

$ uv run python labs/idea_scorer.py
5 ideas scored against 5 criteria
top: Repeated questions (6.0), first written 2026-08-19T22:41:06

$ head -12 glados/data/scored_ideas.json
{
  "scored_at": "2026-08-19T22:41:06",
  "criteria": {
    "lightweight": 3.0,
    "cached": 2.5,
    "gate": 2.5,
    "smoothing": 2.0,
    "local": 1.0
  },
  "ideas": [
    {
      "title": "Repeated questions",

$ uv run python labs/idea_scorer.py   # after raising "lightweight" to 4.0
5 ideas scored against 5 criteria
top: Wake word latency (6.5), first written 2026-08-19T22:41:06

One weight moved by a point and the weekend's first job changed. That is weighted scoring doing exactly what it promises: the keywords choose who is in the running, the weights choose who wins. If a single point can flip your top two, the two ideas were close, and the file now says so in a form you can read next month.

Storing criteria beside the ideas is the part I would not skip. A score of 6.0 on its own is a number with no meaning attached; 6.0 next to the dict that produced it is a decision with its reasoning stapled on, and diff across two saved files shows you the weight that moved and the order that moved with it. Note also what the second run did not do. The ideas came back from disk with their original created_at intact, because the loaded record carries a non-empty stamp and the guard in __post_init__ declines to overwrite it, so re-scoring an old list never makes it look freshly invented.