Canvas Zybooks

canvas-zybooks

Produce a verified local draft for written homework, take-home exams, or reading-completion evidence whose real content is backed by zyBooks.

Contract

Require course_id, assignment_id, current assignment snapshot, approved plan item, and run_dir. Create the work directory with:

from src.course_artifacts import ensure_stable_work_dir

work_dir = ensure_stable_work_dir(run_dir, course_id, assignment_id)

The name is exactly course-<course_id>__assignment-<assignment_id>.

Write one canonical result through src.course_artifacts.write_course_result:

• draft_ready: local artifact exists and checks pass;
• skipped: intrinsically manual or unsupported protected work;
• error: missing required source/authentication or persistent verification failure.

This skill is read-only against Canvas and zyBooks and never uploads to GradeScope. Do not call src.zybooks_client.post, Canvas POST/PUT, or a submission endpoint. A later mutation workflow needs its own explicit authority; for Canvas that means a signed target/action/session-exact receipt validated by src.authorization.

Private overlay

Read _private/canvas-zybooks-app.md and select the current course block. It may define the zyBook code, local token path, course-context primer, instructor notation, assignment naming patterns, and render settings.

If it is missing, write error with reason_code=missing_course_overlay. Never place a JWT, cookie, real course identifier, or instructor identity in a tracked skill or artifact meant for public release.

Artifact tree

spec.md
references/
zybook_exercises/
research_findings.md          # conditional
solutions.md
draft/solutions.pdf
verification.log
audit/round-1.json
result.json

Stage 1: classify and parse the instructor specification

Classify from real evidence:

• Canvas HTML table of graded exercises → written_homework;
• attached exam/problem-set PDF → take_home_exam;
• assigned sections without a written deliverable → reading_completion.

For the standard HTML table, call the existing deterministic parser:

from src.zybooks_spec_parser import parse_homework_spec

exercise_refs = parse_homework_spec(assignment.get("description") or "")

The parser intentionally extracts only the graded column. Save exact chapter.section.exercise references and requested parts to spec.md. For a PDF, download the actual file and extract every question/part. If the exercise set cannot be established, write error rather than guessing from the title.

Stage 2: read exercise content

Validate local authentication with a read-only call such as src.zybooks_client.whoami(). Read section exercises with src.zybooks_client.exercises_for_section(chapter, section) and convert each matching resource using src.zybooks_client.exercise_to_dict(...).

Cache only the assignment-local normalized exercise text under zybook_exercises/; never copy the token. Match every requested reference and part. A missing or expired token, missing section, or unmatched exercise is an error with a precise reason and no fabricated substitute.

reading_completion remains read-only: produce a local checklist/study record unless a separately authorized external workflow exists. Do not mark participation or completion here.

Stage 3: research before improvising

Use this stage for a new table shape, proof method, notation system, or current rubric issue seen in recent feedback. Spawn these native Codex subagents in parallel:

1. spec verifier — read spec.md and raw exercise text; list every required part, hard constraint, and ambiguity.
2. quality inferrer — read the same material plus recent grader comments; infer recurring notation and reasoning risks, clearly labeling inference.
3. template-fit checker — only when the standard homework/exam/reading flow does not cover the deliverable.

Keep subagents read-only and give them raw artifacts rather than expected answers. Save the main session's synthesis to research_findings.md.