Catalog My learning Blog
LLM Evals Course: Error Analysis, LLM Judges and RAG Evals · Phase 2 · Lesson 6 · 4 min read

Code-Based Graders for LLM Evals: Assertions

On this page
  1. Code-based graders: start with checks a script can do
  2. Example code graders for DocsBot
  3. Keep each grader narrow
  4. When code graders aren't enough
  5. Check yourself

Code-based graders: start with checks a script can do

Look at DocsBot's failure modes from Day 3 and ask of each one: could a short function decide this? More often than people expect, the answer is yes.

  • "Missing citation": does the answer contain a docs link?
  • "Cites a page that doesn't exist": is the linked path in the docs index?
  • "Ignores plan": does a Starter answer mention an Enterprise-only feature by name?
  • Format rules: is the tool call valid JSON matching the schema, is the answer under 200 words?

A code-based grader is a function that takes the output, and sometimes the example, and returns pass or fail. It costs nothing, runs in milliseconds, and gives the same result every time. That last property matters: when a code grader's score moves, the app changed, not the grader.

Example code graders for DocsBot

Python
# graders.py: deterministic checks for DocsBot answers
import re

DOC_LINK = re.compile(r"https://docs\.acme\.example/([a-z0-9\-/]+)")
DOCS_INDEX = {"account/reset-password", "security/sso", "billing/plans", "data/export"}
ENTERPRISE_ONLY = {"sso", "audit log", "custom roles"}

def has_citation(answer: str) -> bool:
    return bool(DOC_LINK.search(answer))

def citations_exist(answer: str) -> bool:
    cited = DOC_LINK.findall(answer)
    return all(path.rstrip("/") in DOCS_INDEX for path in cited)

def respects_plan(answer: str, plan: str) -> bool:
    if plan == "enterprise":
        return True
    text = answer.lower()
    explains_setup = any(f"set up {f}" in text or f"configure {f}" in text for f in ENTERPRISE_ONLY)
    return not explains_setup

def grade(example: dict, answer: str) -> dict:
    results = {"has_citation": has_citation(answer), "citations_exist": citations_exist(answer)}
    if "plan" in example:
        results["respects_plan"] = respects_plan(answer, example["plan"])
    return results

if __name__ == "__main__":
    ex = {"input": "How do I set up SSO?", "plan": "starter"}
    bad = "To configure SSO, open Settings. See https://docs.acme.example/security/sso-setup"
    good = "SSO is available on Enterprise. See https://docs.acme.example/billing/plans"
    print(grade(ex, bad))
    print(grade(ex, good))

Running it prints:

Code
{'has_citation': True, 'citations_exist': False, 'respects_plan': False}
{'has_citation': True, 'citations_exist': True, 'respects_plan': True}

The first answer fails twice: it cites a page that doesn't exist, and it explains SSO setup to a Starter customer.

Keep each grader narrow

Notice that respects_plan doesn't try to decide whether the whole answer is right. It checks one thing a regex can see: whether the answer walks a lower-plan user through an Enterprise feature. Narrow checks are easier to trust and easier to debug.

The risk with code graders is false confidence from a loose rule. has_citation passes an answer that links the homepage. Test each grader on a handful of known good and bad outputs, the way you'd test any function, and tighten it when it lets something through.

When code graders aren't enough

Some questions need understanding, not pattern matching: is the answer supported by the cited page, is the tone appropriate, did the bot answer what was asked. A regex for those turns into an unmaintainable list of phrases. Those go to an LLM judge (Day 8).

A useful rule: if two people could disagree about the verdict, it's a judge's job. If they couldn't, write code.

TipRun code graders on every example in every run, including production traffic (Day 27). They're cheap enough to apply everywhere and make a good first filter before expensive judges.

Check yourself

Code grader. Parse the JSON and validate it against the tool's schema. The verdict is unambiguous, runs in microseconds, costs nothing and never disagrees with itself, so there's no reason to involve an LLM.

The rule is too loose, for example accepting any link. Test it on known bad outputs and tighten it, for instance by also requiring the cited page to exist and match the topic.

Narrow checks are easy to verify and their failures point at a specific problem. A broad function hides which rule failed and is hard to trust.

Format and structure, like valid JSON or required fields; presence of citations or links; banned phrases; length limits; and exact values such as a price that must match the catalog.

When judging requires understanding meaning, like whether an answer is supported by the documents or answers the question. Those need an aligned LLM judge or human review.