# subwaymatch/jupygrader architecture

> Architecture diagram of the GitHub repository subwaymatch/jupygrader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/subwaymatch/jupygrader
- Repository: https://github.com/subwaymatch/jupygrader

## Overview

Jupygrader is a notebook-grading package with two instructor workflows: generate a student-facing assignment from a solution notebook, or grade submitted notebooks and produce reviewable results. The main grading path accepts submissions through the public API, coordinates per-notebook execution or full-AI tasks, then packages scores and reports. Separate capabilities include manual and hybrid grading, hidden-test obfuscation, extracted student code, and integrity hashes. Edges reflect the supplied source excerpts, SOURCE INDEX references, and README; unsampled subsystem details and some integrations are therefore omitted or marked unverified.

Main entry points: [`src/jupygrader/grading/batch_grading_manager.py`](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grading/batch_grading_manager.py) (Batch coordinator), [`src/jupygrader/grading/execution_grading_task.py`](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grading/execution_grading_task.py) (Notebook execution), [`src/jupygrader/grading/ai_grader.py`](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grading/ai_grader.py) (AI grading), [`src/jupygrader/models/results.py`](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/models/results.py) (Grading results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_assignment["Assignment authoring"]
  node_cli["CLI<br/>[cli.py]"]
  node_assignment_generation["Assignment generation"]
  node_obfuscation["Test obfuscation<br/>[obfuscate.py]"]
end

subgraph group_grading["Grading workflow"]
  node_notebook_ops["Notebook operations"]
  node_public_api["Grading API<br/>[grader.py]"]
  node_batch_manager["Batch coordinator"]
  node_base_task["Task lifecycle"]
  node_config["Grading configuration<br/>[config.py]"]
  node_utils["File and template utilities<br/>[utils.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_execution_task["Notebook execution"]
  node_full_ai_task["Full AI grading"]
  node_ai_grader["AI grading<br/>[ai_grader.py]"]
  node_ai_models["AI grading modes<br/>[ai_models.py]"]
  node_cell_templates["Grader cell templates"]
end

subgraph group_reporting["Results and reports"]
  node_results["Grading results<br/>[results.py]"]
  node_html_export["HTML report export<br/>[html_export.py]"]
end

node_instructor(("Instructor"))
node_submission["Notebook submission"]
node_openai{{"OpenAI-compatible service"}}

node_instructor -->|"runs commands"| node_cli
node_cli -->|"generates assignment"| node_assignment_generation
node_assignment_generation -->|"obfuscates tests"| node_obfuscation
node_assignment_generation -->|"detects test cases"| node_notebook_ops
node_instructor -->|"submits grading request"| node_public_api
node_submission -->|"provides notebooks"| node_public_api
node_public_api -->|"creates coordinator"| node_batch_manager
node_batch_manager -->|"dispatches execution"| node_execution_task
node_batch_manager -->|"dispatches full AI"| node_full_ai_task
node_batch_manager -->|"configures batch"| node_config
node_execution_task -->|"extends lifecycle"| node_base_task
node_execution_task -->|"preprocesses notebook"| node_notebook_ops
node_execution_task -->|"loads grader scripts"| node_cell_templates
node_execution_task -->|"requests AI review"| node_ai_grader
node_full_ai_task -->|"grades notebook content"| node_ai_grader
node_ai_grader -.->|"requests model grading"| node_openai
node_ai_grader -->|"validates AI results"| node_ai_models
node_execution_task -->|"records test outcomes"| node_results
node_full_ai_task -->|"records AI outcomes"| node_results
node_base_task -->|"extracts user code"| node_notebook_ops
node_base_task -->|"exports HTML report"| node_html_export
node_html_export -->|"renders result details"| node_results
node_batch_manager -->|"collects batch results"| node_results
node_batch_manager -->|"caches remote files"| node_utils

click node_cli "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/cli.py"
click node_assignment_generation "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/generate_assignment.py"
click node_obfuscation "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/obfuscate.py"
click node_notebook_ops "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/notebook_operations.py"
click node_public_api "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grader.py"
click node_batch_manager "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grading/batch_grading_manager.py"
click node_base_task "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grading/base_grading_task.py"
click node_execution_task "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grading/execution_grading_task.py"
click node_full_ai_task "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grading/full_ai_grading_task.py"
click node_ai_grader "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grading/ai_grader.py"
click node_config "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/models/config.py"
click node_ai_models "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/models/ai_models.py"
click node_results "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/models/results.py"
click node_html_export "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/html_export.py"
click node_cell_templates "https://github.com/subwaymatch/jupygrader/tree/main/src/jupygrader/resources/jupyter_cell_scripts"
click node_utils "https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_assignment_generation,node_obfuscation toneBlue
class node_notebook_ops,node_public_api,node_batch_manager,node_base_task,node_config,node_utils toneAmber
class node_execution_task,node_full_ai_task,node_ai_grader,node_ai_models,node_cell_templates toneMint
class node_results,node_html_export toneRose
class node_instructor,node_submission,node_openai toneIndigo
```

## Components

### Assignment authoring

- [CLI](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/cli.py): `src/jupygrader/cli.py`
- [Assignment generation](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/generate_assignment.py): `src/jupygrader/generate_assignment.py`
- [Test obfuscation](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/obfuscate.py): `src/jupygrader/obfuscate.py`

### Grading workflow

- [Notebook operations](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/notebook_operations.py): `src/jupygrader/notebook_operations.py`
- [Grading API](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grader.py): `src/jupygrader/grader.py`
- [Batch coordinator](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grading/batch_grading_manager.py): `src/jupygrader/grading/batch_grading_manager.py`
- [Task lifecycle](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grading/base_grading_task.py): `src/jupygrader/grading/base_grading_task.py`
- [Grading configuration](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/models/config.py): `src/jupygrader/models/config.py`
- [File and template utilities](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/utils.py): `src/jupygrader/utils.py`

### Evaluation

- [Notebook execution](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grading/execution_grading_task.py): `src/jupygrader/grading/execution_grading_task.py`
- [Full AI grading](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grading/full_ai_grading_task.py): `src/jupygrader/grading/full_ai_grading_task.py`
- [AI grading](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/grading/ai_grader.py): `src/jupygrader/grading/ai_grader.py`
- [AI grading modes](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/models/ai_models.py): `src/jupygrader/models/ai_models.py`
- [Grader cell templates](https://github.com/subwaymatch/jupygrader/tree/main/src/jupygrader/resources/jupyter_cell_scripts): `src/jupygrader/resources/jupyter_cell_scripts`

### Results and reports

- [Grading results](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/models/results.py): `src/jupygrader/models/results.py`
- [HTML report export](https://github.com/subwaymatch/jupygrader/blob/main/src/jupygrader/html_export.py): `src/jupygrader/html_export.py`

### Other components

- **Instructor**
- **Notebook submission**
- **OpenAI-compatible service**

## Connections

- Instructor → CLI: runs commands (evidence: `README.md`)
- CLI → Assignment generation: generates assignment (evidence: `src/jupygrader/cli.py`)
- Assignment generation → Test obfuscation: obfuscates tests (evidence: `src/jupygrader/generate_assignment.py`)
- Assignment generation → Notebook operations: detects test cases (evidence: `src/jupygrader/generate_assignment.py`)
- Instructor → Grading API: submits grading request (evidence: `README.md`)
- Notebook submission → Grading API: provides notebooks (evidence: `README.md`)
- Grading API → Batch coordinator: creates coordinator (evidence: `src/jupygrader/grader.py`)
- Batch coordinator → Notebook execution: dispatches execution (evidence: `src/jupygrader/grading/batch_grading_manager.py`)
- Batch coordinator → Full AI grading: dispatches full AI (evidence: `src/jupygrader/grading/batch_grading_manager.py`)
- Batch coordinator → Grading configuration: configures batch (evidence: `src/jupygrader/grading/batch_grading_manager.py`)
- Notebook execution → Task lifecycle: extends lifecycle (evidence: `src/jupygrader/grading/execution_grading_task.py`)
- Notebook execution → Notebook operations: preprocesses notebook (evidence: `src/jupygrader/grading/execution_grading_task.py`)
- Notebook execution → Grader cell templates: loads grader scripts (evidence: `src/jupygrader/grading/execution_grading_task.py`)
- Notebook execution → AI grading: requests AI review (evidence: `src/jupygrader/grading/execution_grading_task.py`)
- Full AI grading → AI grading: grades notebook content (evidence: `src/jupygrader/grading/full_ai_grading_task.py`)
- AI grading → OpenAI-compatible service: requests model grading
- AI grading → AI grading modes: validates AI results (evidence: `src/jupygrader/grading/ai_grader.py`)
- Notebook execution → Grading results: records test outcomes (evidence: `src/jupygrader/grading/execution_grading_task.py`)
- Full AI grading → Grading results: records AI outcomes (evidence: `src/jupygrader/grading/full_ai_grading_task.py`)
- Task lifecycle → Notebook operations: extracts user code (evidence: `src/jupygrader/grading/base_grading_task.py`)
- Task lifecycle → HTML report export: exports HTML report (evidence: `src/jupygrader/grading/base_grading_task.py`)
- HTML report export → Grading results: renders result details (evidence: `src/jupygrader/html_export.py`)
- Batch coordinator → Grading results: collects batch results (evidence: `src/jupygrader/grading/batch_grading_manager.py`)
- Batch coordinator → File and template utilities: caches remote files (evidence: `src/jupygrader/grading/batch_grading_manager.py`)
