Gradebook: Weighted Categories, Late Work and Curves

District Gradebook

You've joined the student-systems team at the Maple Ridge School District. The gradebook service turns the marks teachers record into the percentages and letter grades printed on report cards. Last Friday's progress reports went out with grades the teachers immediately disputed (tickets GRD-301 to GRD-312, Part 1). Once those are fixed, the board has approved two policy changes (Part 2), and teachers and the registrar have asked for grade curves and an audit trail (Part 3). All grade arithmetic is exact: inside the service every number is a fractions.Fraction, and nothing may ever go through floating point.

Codebase

Conventions that live in the code, not here: the letter cutoffs and the "incomplete" marker are in config.py; the display rules are in report.py (this README states them in "Reading a grade"); category names are matched through names.canonical_category (trim, collapse inner whitespace, case-fold; ids are *not* normalized); scoring.counted_items is the one place that decides what counts.

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh gradebook and returns one result per operation. Every operation is [name, *args]. Errors are returned as "error: <code>" strings, never raised. An unknown (or non-string) operation name returns "error: unknown operation"; a wrong number of arguments returns "error: invalid arguments". A failed operation changes nothing.

• Ids (course_id, assignment_id, student_id, prefix) and category names must be non-empty strings, otherwise invalid arguments (checked first, before any lookup).
• Points (marks and points possible) are a non-negative integer or a decimal string with at most two decimals ("7.5", "17.99", "0.25"). Floats, booleans, negative or malformed values are invalid points.
• Days are non-negative integers counted from the first day of term (day 0); booleans are not integers. The registrar's clock starts at day 0 and is shared by every course.

• A course's categories are [name, weight] pairs; weights are whole percents that total exactly 100.
• score and excuse replace whatever was recorded before for that student and assignment: a new score replaces an excuse, an excuse replaces a score. Nothing recorded means "not yet recorded".
• score_all is a bulk helper for load testing: the *i*-th enrolled student (counting from 0) gets (base + i*step) mod (floor(points_possible) + 1) points, replacing whatever was recorded.

Reading a grade

grade returns {"percent": <text or null>, "letter": <letter>, "categories": [[name, text or null], ...]} with the categories in the course's creation order and names in canonical form.

• Percent text has exactly one decimal place and rounds halves up (84.25 shows as "84.3", 72.349 as "72.3"), computed exactly.
• Letters: A at 90 or more, B at 80, C at 70, D at 60, otherwise F. The letter is decided from the exact percentage, not from the text that is shown: 89.95 shows as "90.0" and is a B.
• A student with nothing countable at all shows {"percent": null, "letter": "INC", ...}.
• class_report returns [student_id, percent text, letter] rows ordered by exact percentage, highest first, ties by student_id in plain string order; students with INC come last, also by student_id.

Part 1: Report-card grades are wrong (GRD-301, GRD-305, GRD-309, GRD-312)

Goal: make grade and class_report follow the rules below.

Complaints from teachers and the registrar:

1. "My students have no quiz grades yet and their report cards show a failing grade." (GRD-301)
2. "Excused homework counts against the student, and an assignment due *today* is already a zero." (GRD-305)
3. "84.25 printed as 84.2. And the calculator says 17.99 out of 20 is a 90, the gradebook says an 89.9." (GRD-309)
4. "The class report puts a student with 100.0 below a student with 99.0." (GRD-312)

Rules

1. What counts, per student and assignment: *excused* (the teacher excused it) does not count; *scored* counts for the recorded points; nothing recorded and today > due_day is *missing* and counts as 0 points; nothing recorded and today <= due_day is *not yet due* and is ignored. (An assignment is due at the end of its due day.) today is the shared clock.
2. Category percentage: total points earned divided by total points possible over the assignments of that category that count (so a 40-point assignment weighs four times a 10-point one). A category in which nothing counts has no percentage and takes no part in the course grade (null in categories).
3. Course percentage: the weight-weighted average of the percentages of the categories that take part, renormalizing the weights: sum(weight * percentage) / sum(weights of participating categories). If no category takes part, the student is INC.
4. Display rules are as in "Reading a grade". Category percentages in categories use the same text rule.

Example

[["open_course", "alg1", [["Homework", 20], ["Quizzes", 30], ["Exams", 50]]],
 ["enroll", "alg1", "ana"], ["enroll", "alg1", "ben"], ["enroll", "alg1", "cy"], ["enroll", "alg1", "dan"],
 ["add_assignment", "alg1", "hw1", "homework", 10, 3], ["add_assignment", "alg1", "hw2", "homework", 20, 6],
 ["add_assignment", "alg1", "q1", "quizzes", 20, 4], ["add_assignment", "alg1", "ex1", "exams", 100, 9],
 ["set_day", 7],
 ["score", "alg1", "hw1", "ana", 8], ["score", "alg1", "q1", "ana", 15],
 ["score", "alg1", "hw1", "ben", 10], ["excuse", "alg1", "hw2", "ben"], ["score", "alg1", "q1", "ben", 12],
 ["excuse", "alg1", "hw1", "dan"], ["excuse", "alg1", "hw2", "dan"], ["excuse", "alg1", "q1", "dan"],
 ["grade", "alg1", "ana"], ["grade", "alg1", "ben"], ["class_report", "alg1"]]

On day 7 the exam (due day 9) is not yet due, so the exams category takes no part. ana missed hw2: homework is 8/30, quizzes 15/20, and the course is (20*8/30 + 30*3/4) / 50 = 55.67, shown as {"percent": "55.7", "letter": "F", "categories": [["homework", "26.7"], ["quizzes", "75.0"], ["exams", null]]}. ben has homework 10/10 (the excused hw2 is out) and quizzes 12/20: "76.0", C. cy recorded nothing, so both homeworks and the quiz are zeros (0.0, F); dan had everything excused (INC). The class report is [["ben", "76.0", "C"], ["ana", "55.7", "F"], ["cy", "0.0", "F"], ["dan", null, "INC"]].

Part 2: Board policy: late work, dropped scores, extra credit (GRD-340)

Goal: implement the board's three policies. Part 1 behaviour is unchanged when no policy is set.

Rules

1. Late penalty. The default policy is 0 per day and 0 cap (no penalty). A score with submitted_day d on an assignment due on day D is max(0, d - D) days late. The penalty is min(per_day * days, cap) percent of the assignment's points possible (not of the points earned), subtracted from the points, and the result never goes below 0. A score without submitted_day is on time. Missing work (a zero) has no penalty. Recording a new score replaces the earlier submitted_day too (leaving it out means on time). The policy is a rule applied when grades are computed, so changing it also changes scores recorded earlier.
2. Drop lowest. set_drop sets how many of the lowest items to drop from one category (default 0). The items eligible are the category's *counting regular* assignments from Part 1 (so excused and not yet due ones are never in play, but missing zeros are eligible and are usually the first to go). "Lowest" means the lowest percentage (points after the late penalty divided by points possible); ties are broken by more points possible first, then by assignment_id in plain string order. At most eligible - 1 items are dropped, so one item always remains. The category percentage is then computed over the items that are left.
3. Extra credit. An extra-credit assignment's points possible are not added to the category's denominator; the points a student earns on it are added to the numerator. It is never eligible to be dropped, and if the student has no score on it (not turned in, even when past due) it simply does not exist for that student. The late penalty applies to its points like any other. A category's percentage is capped at 100% after extra credit is added. A category with only extra-credit items counting (no regular item) takes no part in the course grade.

Example

[["open_course", "bio", [["Labs", 40], ["Tests", 60]]], ["enroll", "bio", "mia"],
 ["add_assignment", "bio", "l1", "labs", 10, 2], ["add_assignment", "bio", "l2", "labs", 40, 4],
 ["add_assignment", "bio", "l3", "labs", 20, 6], ["add_assignment", "bio", "t1", "tests", 50, 5],
 ["add_assignment", "bio", "b1", "labs", 5, 6, true],
 ["set_day", 7], ["set_late_policy", "bio", "10", "30"], ["set_drop", "bio", "labs", 1],
 ["score", "bio", "l1", "mia", 8], ["score", "bio", "l2", "mia", 36, 6], ["score", "bio", "l3", "mia", 13],
 ["score", "bio", "t1", "mia", 45], ["score", "bio", "b1", "mia", 4],
 ["grade", "bio", "mia"]]

l2 was two days late: 20% of 40 points is 8, so it is worth 28/40. The labs percentages are l1 80%, l2 70% and l3 65%, so l3 is dropped (dropping by raw points would drop l1). The labs are (8 + 28) / (10 + 40) = 72%, plus the 4 extra-credit points over the same 50: 80%. Tests are 90%, and the course is 0.4*80 + 0.6*90 = 86.0: {"percent": "86.0", "letter": "B", "categories": [["labs", "80.0"], ["tests", "90.0"]]}.

Part 3: Curves and the grade audit trail (GRD-377, GRD-380)

Goal: teachers can curve a single assignment, and the registrar can see every change to a student's displayed grade. A curve is applied to the points of each assignment before anything is totalled, which changes what the earlier Parts' rules operate on.

Curve rules. kind is one of "add", "median", "sqrt" or "none"; anything else is invalid curve. An assignment has at most one curve: a new curve call replaces the old one, and "none" removes it.

1. "add": value is a decimal (as for points) greater than 0; every curved score gets that many more points.
2. "sqrt": value must be null. A raw score r on an assignment worth P points becomes sqrt(r * P) rounded down to a multiple of 0.01, computed exactly (36 of 100 becomes 60; 50 of 100 becomes 70.71).
3. "median": value is a target percentage, a decimal greater than 0 and at most 100. Take the *raw* points of every enrolled student who has a recorded score on this assignment (excused students, missing work and students with nothing recorded are not part of it), find their median (the mean of the two middle values when there is an even number of them), and let bump = max(0, value% of P - median). Every one of those students' scores gets bump more points. The curve is a rule evaluated on the scores as they stand: if any student's score changes, the bump changes for everyone.
4. A curve applies to recorded scores only; missing work stays a zero. Invalid values (wrong type for the kind, out of range, or not null for "sqrt"/"none") are invalid curve.
5. Order of adjustments for one score: curve, then cap at the assignment's points possible, then the late penalty (Part 2), then the floor at 0. Everything after that, including which items are the lowest for set_drop, works with these adjusted points. Extra-credit assignments can be curved too.

Audit rules. After every operation that succeeds, each enrolled student whose displayed grade (percent text and letter) is different from what it was before the operation gets one entry in their history, oldest first: {"op": <0-based position of the operation in the run() list>, "name": <operation name>, "from": {"percent": ..., "letter": ...}, "to": {...}}. This includes changes caused by *someone else's* mark under a median curve, by set_day making work overdue, by a new assignment, by a policy change and by score_all. A change in the exact percentage that leaves the displayed percent and letter the same is not logged; a letter change with the same text is. Enrolling a student sets their starting grade and writes no entry. Failed operations write nothing.

Scale. Classes of a few hundred students with several median-curved assignments and hundreds of marks recorded one at a time must still run in a couple of seconds.

Example

[["open_course", "hist", [["Essays", 100]]],
 ["enroll", "hist", "ana"], ["enroll", "hist", "ben"], ["enroll", "hist", "cy"], ["enroll", "hist", "dan"],
 ["add_assignment", "hist", "e1", "essays", 100, 3],
 ["score", "hist", "e1", "ana", 60], ["score", "hist", "e1", "ben", 70],
 ["score", "hist", "e1", "cy", 80], ["score", "hist", "e1", "dan", 90],
 ["curve", "hist", "e1", "median", 85],
 ["score", "hist", "e1", "ana", 75],
 ["history", "hist", "ben"]]

The raw median is 75, so the curve adds 10 points to everyone (ana 70, ben 80, cy 90, dan 100). Re-scoring ana as 75 moves the median to 77.5, the bump to 7.5, and every student's grade, including ben's: [{"op": 7, "name": "score", "from": {"percent": null, "letter": "INC"}, "to": {"percent": "70.0", "letter": "C"}}, {"op": 10, "name": "curve", "from": {"percent": "70.0", "letter": "C"}, "to": {"percent": "80.0", "letter": "B"}}, {"op": 11, "name": "score", "from": {"percent": "80.0", "letter": "B"}, "to": {"percent": "77.5", "letter": "C"}}].

Notes

• You may use the AI assistant freely; you are expected to verify what it produces.
• Later Parts must not break earlier ones; hidden tests re-check earlier behaviour after each Part.
• If this README and the code seem to disagree about letter cutoffs or name handling, config.py and names.py win; for everything else the README wins.