Evaluation is a decision protocol
How to study this lesson
Read one section, trace the worked example, and try the knowledge check. Bookmark saves a shortcut; notes appear in My notebook. Mark lesson complete is your own assessment and does not mark its lab passed.
By the end, you can
- Compute precision, recall, F1, and expected error cost.
- Choose a threshold on validation data.
- Prevent leakage and interpret small-sample uncertainty.
Begin with the decision and its errors
Evaluation starts with what the system will decide. A support router might escalate a request or let automation continue. A false negative leaves a difficult request unattended; a false positive consumes a reviewer slot. These outcomes have different costs, so one overall accuracy value cannot determine whether the router is useful.
A confusion matrix counts true positives, false positives, false negatives, and true negatives after applying a threshold. Precision is the fraction of predicted positives that are real positives. Recall is the fraction of actual positives that were found. F1 is the harmonic mean of precision and recall, but it does not encode every business cost or capacity constraint. Select metrics because they answer the operational question, not because a library prints them by default.
A threshold trades workload for missed cases
Consider labels [1, 0, 1, 0] and probabilities [0.9, 0.6, 0.4, 0.1]. At threshold 0.5, the first two cases are positive: one true positive, one false positive, and one missed positive. Precision and recall are both 0.5. At threshold 0.3, the first three are positive: two true positives and one false positive. Precision is two thirds and recall is one.
If a false positive costs one unit and a false negative costs five, threshold 0.5 costs six units while threshold 0.3 costs one. This toy comparison favors the lower threshold. A real team must also consider reviewer capacity, changing prevalence, probability calibration, and uncertainty. A threshold is a policy derived from evidence, rather than an intrinsic property of the model.
Split according to the deployment question
Training data fits parameters. Validation data selects models, prompts, thresholds, and other choices. Test data estimates performance after those choices are fixed. Repeatedly inspecting the test score and adjusting your system turns the test set into another validation set, even if no code explicitly trains on its labels.
Random row splits can leak related information. If many tickets belong to the same customer, put that customer's related records on one side of a group split when the question is generalization to new customers. For future traffic, a time-based split may better resemble deployment. Fit scalers, feature selectors, and vocabulary decisions using training data where required. The correct split follows the intended use, not a universal percentage recipe.
Count uncertainty and inspect slices
A result of nine successes out of ten has the same observed rate as 900 out of 1,000, but much less evidence behind it. Report the denominator and use an uncertainty estimate appropriate for the design. When comparing two versions on the same tasks, paired differences can be more informative than pretending the two results came from unrelated samples.
Inspect slices that matter to the decision, such as language, input length, tool availability, or request category. A higher overall score can hide a severe regression on a small but important group. Slice analysis should be planned where possible; searching hundreds of tiny groups until one looks impressive invites chance findings. Preserve example IDs and error categories so a reviewer can inspect specific failures rather than only aggregated numbers.
Make the evaluation reproducible
The example prints metrics and a chosen error-cost function for two thresholds on one fixed fixture. It defines a positive prediction as p greater than or equal to the threshold, making the boundary behavior explicit. It returns zero precision when no positives are predicted, which is a documented convention rather than a claim that an undefined mathematical ratio has a natural value.
For an agent, extend the record beyond answer correctness. Count tool success, unnecessary calls, latency, cost, and whether completion claims match evidence. Keep a deterministic offline suite for software behavior and a separate model evaluation for probabilistic quality. Together they distinguish a broken parser from a reasoning failure. The project asks you to turn these principles into a threshold report that another engineer can rerun and challenge.
Work through the code
Two thresholds are compared on four labeled examples with false-negative cost five. This small snippet assumes already validated binary labels and equal-length inputs; the lab adds those checks. Zero-denominator conventions are explicit. The fixture teaches arithmetic and is not sufficient evidence for choosing a production threshold.
def metrics(labels, scores, threshold):
predicted = [score >= threshold for score in scores]
tp = sum(y == 1 and p for y, p in zip(labels, predicted))
fp = sum(y == 0 and p for y, p in zip(labels, predicted))
fn = sum(y == 1 and not p for y, p in zip(labels, predicted))
precision = tp / (tp + fp) if tp + fp else 0.0
recall = tp / (tp + fn) if tp + fn else 0.0
f1 = 2 * precision * recall / (precision + recall) if precision + recall else 0.0
return precision, recall, f1, fp + 5 * fn
labels = [1, 0, 1, 0]
scores = [0.9, 0.6, 0.4, 0.1]
for threshold in (0.5, 0.3):
precision, recall, f1, cost = metrics(labels, scores, threshold)
print(f"t={threshold:.1f} precision={precision:.3f} recall={recall:.3f}")
print(f"f1={f1:.3f} cost={cost}")
t=0.5 precision=0.500 recall=0.500 f1=0.500 cost=6 t=0.3 precision=0.667 recall=1.000 f1=0.800 cost=1
Run Python snippets locally with the prerequisites named above. The module coding lab runs directly in your browser.
Pause and reason
You test 50 prompt variants on the same 30 examples, choose the best, and report that score as expected production accuracy. What is wrong, and what should you do next?
Check your understanding
Your router catches every difficult request but sends nearly every request to a human. Which metric exposes the workload problem most directly?
Your notes
Explain the mechanism in your own words. Add a failure you want to test.