Skip to content

feat(grades): list your own grades with edstem grades - #18

Merged
bunizao merged 5 commits into
bunizao:mainfrom
MortyYJT:feat/lessons-score
Nov 3, 2026
Merged

bunizao merged 5 commits into
bunizao:mainfrom
MortyYJT:feat/lessons-score

Conversation

@MortyYJT

@MortyYJT MortyYJT commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

There was no way to ask edstem-cli "what did I get for this assignment". Tools that need it read the token file and call Ed directly, duplicating auth, region and retry handling. This adds a read-only edstem grades [list] UNIT [queries...] that lists the signed-in user's own final-submission grades for a unit, following the family's command model and moodle-cli's grades words.

$ edstem grades CS101 assignment --json
[
  { "lessonId": 7001, "title": "Assignment 1", "status": "graded", "grade": 7.5, "max": 10, "submittedAt": "2026-03-02T10:00:00+11:00" },
  { "lessonId": 7002, "title": "Assignment 2", "status": "unreleased", "submittedAt": "2026-03-09T10:00:00+11:00" },
  { "lessonId": 7003, "title": "Assignment 3", "status": "not_submitted" }
]
status meaning
graded released; grade is the final mark, max is derived as the sum of Ed's slide totals (omitted if any total is unreadable)
ungraded released, but staff have not graded you yet
unreleased Ed answers 403 results_unreleased until staff release results
not_submitted no final submission
unavailable Ed refused this one lesson; error says why and the rest of the unit is still listed
  • src/ed/client.ts: fetchLessonAttempts(lessonId, userId) reads GET lessons/{id}/attempts/{userId}, and fetchLessonMarkingStatus(lessonId, attemptId) reads GET lessons/{id}/marking_status?attempt={id}, both through the existing private get(). EdApiError gains an optional code holding Ed's own error code; it defaults to "", so existing callers are unaffected.
  • src/ed/operations.ts: listGrades resolves the unit and lessons the way lessons mark-read UNIT [queries...] does (the query matcher is now one shared helper), and only queries lessons whose kind is "attempt". In two real units that was exactly the submission lessons (3 of 42, 1 of 12), so content lessons cost no requests. A staff mark_override on the final attempt, including zero, replaces the calculated mark, as in Ed's web client (attempt.markOverride ?? sum(userSlideMarks)); it is applied after the release check. A failing lesson becomes unavailable; a rejected token or a network failure still stops the listing. The ownership checks throw a plain Error.
  • src/ed/projections.ts: projectGrade is an allowlist. Ed's result also carries the student's name, email and sourced_id, plus other users' IDs; none of them are printed.
  • CLI: a grades noun with the list verb, so edstem grades UNIT [words...] defaults to list and edstem grades alone gives the unit picker at a terminal or a usage error with the usage line elsewhere. unreleased and unavailable are outside the shared status vocabulary, so tables tone them warning and danger.
  • Docs: a Grade term in CONTEXT.md, a row in the README table and in the skill intent table, and a regenerated SKILL.md.

GET only: it never starts, saves or submits an attempt. The attempts path uses the token owner's ID, and both the final attempt and attempt_result must belong to that user. MCP gets no new tool here; get_grades can follow in a separate PR.

Tests

npm run check, npm run test:node (330 passing at 937f54f; 328 before the review follow-up), npm run build:local and npm run skill:generate all pass; SKILL.md is committed. bun test tests/remote (22) and bun test tests/worker (10) passed at d9c5124; 937f54f does not touch them and they were not re-run locally (no Bun here).

  • Client: the attempts and marking URLs, parsing, final_id: null, mark_override, an unreadable slide total, and code kept on a 403.
  • listGrades: each status; the kind and query filters (a content lesson is never queried); an override including zero, with no calculated mark, and while unreleased; one failing lesson reported as unavailable while the next is still listed; auth and network failures stopping the listing; an attempt or result owned by someone else becoming unavailable without its data.
  • CLI: grades 100 --json prints only allowlisted fields (no name, email or other user IDs) and sends only GETs; query words narrow the rows; seven query words still default to list; unreleased and unavailable are coloured in a table.

No test reaches the real Ed API: every test drives EdClient with a mocked fetch or a mocked client.

Not verified

Ed does not document either endpoint; their shapes come from live responses. I ran the built CLI against a live AU account on one of my own units: two graded, matching the values an earlier direct-API script returned, and one unreleased; a query narrowed it to one row. Not exercised live: ungraded, not_submitted, unavailable, a non-null mark_override, and the US and EU regions. kind: "attempt" was checked on two units only.

Add a read-only `edstem lessons score <lessons...>` that reports the
signed-in user's final-submission result per lesson: graded (score,
maxScore, submittedAt), unmarked, unreleased, or not_submitted.

EdApiError now keeps Ed's error code, so Ed's 403 results_unreleased is
reported as a status rather than an error. The projection is an
allowlist: Ed's result also carries the student's name and email and
other unmarked users' IDs, none of which are printed.
@bunizao

bunizao commented Oct 29, 2026

Copy link
Copy Markdown
Owner

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-29T03:12:14.432644Z 293fb57 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 293fb575d5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/ed/operations.ts Outdated
return { ...submitted, status: "unmarked" };
}
const maxScore = marking.slideTotals.reduce((sum, total) => sum + total, 0);
return { ...submitted, maxScore: maxScore > 0 ? maxScore : null, score: marking.mark, status: "graded" };

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Apply the final attempt's mark override

When the final attempt has a non-null mark_override, fetchLessonAttempts discards that field and this line always publishes attempt_result.mark. Instructor-adjusted submissions can therefore report the pre-override score (or become unmarked if the calculated mark is null); carry the final attempt's override through and apply it after the results-release check, including an override of zero.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed and fixed in c868aab. Ed's web client computes the student's final mark as attempt.markOverride ?? sum(userSlideMarks), so the override wins, including zero. It now applies after the results_unreleased check, and also when Ed has no calculated mark. Three new tests cover override, zero override, and override-while-unreleased.

Ed's web client shows the final attempt's mark_override in place of the
calculated mark, including an override of zero. Apply it after the
results-release check, so an override stays hidden until release.
@bunizao

bunizao commented Oct 29, 2026

Copy link
Copy Markdown
Owner

Hi @MortyYJT and thanks for the contribution! This is solid work. I like the privacy allowlist, and the ownership checks are exactly right. The changes below are mostly about fitting the command into the rest of the unicorn ecosystem.

Blocking

  • Rename to a grades noun. score isn't in cli-kit's verb set (list, show, read, get, search, send, submit, set, mark-read), and moodle-cli already exposes moodle grades [UNIT]. Please make it edstem grades [list] UNIT [queries...].
  • Scope by unit and lesson name, not by lesson ID. Resolve lessons the way lessons mark-read UNIT [queries...] does, and include title in each row.
  • Use moodle's words. score/maxScore → grade/max, unmarked → ungraded. In CONTEXT.md the term becomes Grade, with Score, Mark under Avoid.
  • One bad lesson shouldn't fail the whole unit. Once this runs across a unit, report that lesson as unavailable instead of exiting.

Non-blocking

  • max is the sum of slide_totals, so it's derived. One line in the docs saying so is enough.
  • The ownership check throws EdApiError("upstream", 0, …). That's an internal invariant, not an HTTP error; a plain Error is more honest than status 0.
  • Is there a cheap field on the lesson that says it's assessed? Without one, grades UNIT costs two requests per lesson.

The override fix in c868aab looks good. An MCP tool can come in a follow-up.

@bunizao

bunizao commented Oct 29, 2026

Copy link
Copy Markdown
Owner

furthermore, i recommend reading https://unicorn.tuuhub.com/docs/concepts/command-model/ as a development reference. (the full Shared behaviour section)

Follow review: a `grades` noun with the shared `list` verb replaces
`lessons score`, scoped by unit and lesson-name queries like
`lessons mark-read`, with moodle's words (grade, max, ungraded) and a
title on each row. Only lessons whose kind is "attempt" are queried,
so content lessons cost no requests. One failing lesson is reported as
unavailable while auth and network errors still stop the listing; the
ownership checks throw a plain Error. unreleased and unavailable get
their own tones in tables.
@MortyYJT

Copy link
Copy Markdown
Contributor Author

Thanks for the careful review and the pointer to the command model. All of it is in d9c5124; the PR description is updated to match.

Blocking

  • grades noun. edstem grades [list] UNIT [queries...] replaces lessons score. edstem grades alone gives the unit picker at a terminal and a usage error with the usage line elsewhere, as the Shared behaviour docs describe.
  • Unit and lesson-name scope. Lessons resolve the same way as lessons mark-read UNIT [queries...]; the query matcher is now one helper both use. Every row has title.
  • moodle's words. grade, max and ungraded. CONTEXT.md has Grade, with Score, Mark under Avoid.
  • One bad lesson. It becomes status: "unavailable" with an error message, and the rest of the unit is still listed. A rejected token or a network failure still stops the run, since every other lesson would fail the same way.

Non-blocking

  • max is described as the sum of Ed's slide totals in CONTEXT.md, the command description and the skill table.
  • The ownership checks now throw a plain Error.
  • Cheap assessed field: yes. The lesson list's kind is "attempt" for lessons that take submissions and "content" otherwise. In two of my units it picked out exactly the submission lessons (3 of 42, 1 of 12), so only those cost the two requests.

Two small additions from reading the Shared behaviour docs: unreleased and unavailable aren't in cli-kit's status vocabulary, so tables tone them warning and danger through render's tones. Also, defaultByArity covers up to 32 arguments, so query words don't need an explicit list.

@MortyYJT MortyYJT changed the title feat(lessons): show your own lesson scores with lessons score feat(grades): list your own grades with edstem grades Oct 29, 2026
@bunizao

bunizao commented Nov 1, 2026

Copy link
Copy Markdown
Owner

The approach looks right to me. A few suggestions, none of them blocking:

  1. Skip the attempts request for lessons you never submitted. listGrades already loads the unit's lessons, and for each lesson that response includes the signed-in user's own submitted_at (and attempt_id). parseLesson currently drops both. If submitted_at is null, the lesson can go straight to not_submitted without calling lessons/{id}/attempts/{userId}. A unit with many weekly quizzes you haven't done would save one request per quiz. Submitted lessons still need the attempts call, because mark_override is only there. I wouldn't use the list's attempt_id in place of final_id, though. After a lesson is reopened, the latest attempt may not be the final submission.

  2. Optional: fetch a few lessons at a time. Lessons are fetched one after another. For a large unit, running two to four at once would make it noticeably faster. With only a handful of submission lessons per unit it hardly matters, so this can wait.

  3. The 33-entry defaultByArity. I understand why it's there: the routing needs one entry per argument count, so edstem grades UNIT word word ... only works up to a fixed number of words. It would be cleaner for the routing to support "any number of arguments means list". That belongs in the shared routing code rather than in this PR, so I'm fine leaving it as is for now.

- Parse the lesson list's submitted_at into Lesson.submittedAt; a lesson
  with none goes straight to not_submitted without the attempts request.
  Submitted lessons still read the attempts, which carry mark_override
  and the final submission.
- Ask Ed about up to three lessons at a time, keeping the unit's order;
  a rejected token or a network failure still fails the listing.
@MortyYJT

MortyYJT commented Nov 1, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the suggestions. 1 and 2 are in 937f54f; 3 is left as is.

  1. Unsubmitted lessons skip the attempts request. parseLesson now keeps the list's submitted_at as Lesson.submittedAt, and a lesson without one goes straight to not_submitted. Submitted lessons still read lessons/{id}/attempts/{userId}, for mark_override and for final_id rather than the list's attempt_id, as you said. On my account, across the 4 attempt lessons in my 3 active units, submitted_at being null matched final_id being null every time.
  2. A few lessons at a time. listGrades now asks about up to 3 lessons at once (GRADE_CONCURRENCY) and keeps the unit's order. A rejected token or a network failure still fails the listing, and no further lessons are started after it.
  3. defaultByArity. Agreed that it belongs in the shared routing. Happy to send that as a separate PR if you'd like.

npm run check, npm run test:node (330 passing) and npm run build:local pass, and SKILL.md is unchanged. I don't have Bun locally, so tests/remote and tests/worker are left to CI. The built CLI against my live account gives the same results as before (two graded and one unreleased on one unit).

@bunizao

bunizao commented Nov 3, 2026

Copy link
Copy Markdown
Owner

LGTM, thx!

@bunizao
bunizao merged commit 64ff7af into bunizao:main Nov 3, 2026
@bunizao

bunizao commented Nov 3, 2026

Copy link
Copy Markdown
Owner

Docs are now available: Grades guide and the edstem grades reference. The command shipped in 0.8.3, and 0.8.4 adds the matching MCP tool, list_grades.

@bunizao bunizao self-assigned this Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants