API reference · grader/models.py · 261 lines

`grader.models`

Structured result types shared by the engine, the store and the UI.

The contract in design.md section 24 is the source of truth for the on-disk shape: every rubric item keeps both automatic_score and final_score so a manual override never destroys the automated result.

Summary

Name	Kind	Description
`ExecutionRecord`	class	Outcome of running one student notebook (design.md section 19).
`RubricItemResult`	class	One graded rubric line (design.md section 24).
`SubmissionResult`	class	Everything known about one student's submission.
`GradingProgress`	class	Snapshot pushed to the UI while grading runs (design.md section 7).
`status_icon()`	function
`status_color()`	function

Constants

Name	Value	Notes
`STATUS_PASS`	`'pass'`
`STATUS_PARTIAL`	`'partial'`
`STATUS_FAIL`	`'fail'`
`STATUS_WARNING`	`'warning'`
`STATUS_MANUAL_REVIEW`	`'manual_review'`
`STATUS_EXECUTION_ERROR`	`'execution_error'`
`STATUS_NOT_FOUND`	`'not_found'`
`ALL_STATUSES`	`(STATUS_PASS, STATUS_PARTIAL, STATUS_FAIL, STATUS_WARNING, STATUS_MANUAL_REVIEW, STATUS_EXECUTION_ERROR, STATUS_NOT_FOUND)`
`STATUS_DISPLAY`	`{STATUS_PASS: ('✓', 'green'), STATUS_PARTIAL: ('⚠', 'yellow'), STATUS_WARNING: ('⚠', 'yellow'), STATUS_MANUAL_REVIEW: ('⚠', 'yellow'), STAT…`	Status -> (icon, colour bucket). Colour is never the only signal (section 15).

Classes

class ExecutionRecord #[source]

dataclass

Outcome of running one student notebook (design.md section 19).

Fields

Name	Type	Default
`success`	`bool`	`False`
`execution_time_seconds`	`float`	`0.0`
`timeout`	`bool`	`False`
`error_cell`	`int \| None`	`None`
`error_message`	`str \| None`	`None`
`traceback`	`str`	`''`
`mode`	`str`	`'docker'`
`attempted`	`bool`	`False`
`log`	`str`	`''`
`executed_notebook_path`	`str \| None`	`None`

Properties

property status: str #[source]: No description.

Methods

to_dict() -> dict[str, Any] #[source]: No description.

classmethod from_dict(data: dict[str, Any]) -> 'ExecutionRecord' #[source]: No description.

class RubricItemResult #[source]

dataclass

One graded rubric line (design.md section 24).

Fields

Name	Type	Default	Notes
`rubric_id`	`str`	required
`name`	`str`	required
`points_possible`	`float`	required
`automatic_score`	`float`	`0.0`
`status`	`str`	`STATUS_NOT_FOUND`
`confidence`	`float`	`1.0`
`feedback`	`str`	`''`
`evidence`	`dict[str, Any]`	`field(default_factory=dict)`
`type`	`str`	`'deterministic'`
`manual_override`	`bool`	`False`	Human intervention (design.md section 11) — never overwrites the automated value.
`manual_score`	`float \| None`	`None`
`override_reason`	`str`	`''`

Properties

property final_score: float #[source]: The manual score when overridden, otherwise the automatic score.

property needs_review: bool #[source]: No description.

Methods

to_dict() -> dict[str, Any] #[source]: No description.

classmethod from_dict(data: dict[str, Any]) -> 'RubricItemResult' #[source]: No description.

class SubmissionResult #[source]

dataclass

Everything known about one student's submission.

Fields

Name	Type	Default	Notes
`student_id`	`str`	required
`display_name`	`str`	`''`
`notebook_path`	`str \| None`	`None`
`submission_dir`	`str \| None`	`None`
`items`	`list[RubricItemResult]`	`field(default_factory=list)`
`execution`	`ExecutionRecord`	`field(default_factory=ExecutionRecord)`
`discovery_warnings`	`list[str]`	`field(default_factory=list)`
`review_reasons`	`list[str]`	`field(default_factory=list)`
`reviewed`	`bool`	`False`
`graded_at`	`str \| None`	`None`
`status`	`str`	`'pending'`	pending \| graded \| error \| skipped
`error`	`str \| None`	`None`
`artifacts`	`dict[str, Any]`	`field(default_factory=dict)`

Properties

property max_score: float #[source]: Sum of the items' possible points.

property automatic_total: float #[source]: No description.

property total_score: float #[source]: Sum of the items' final scores.

property percentage: float | None #[source]: No description.

property confidence: float | None #[source]: Lowest item confidence — the weakest link decides trust in the grade.

property has_manual_override: bool #[source]: No description.

property needs_review: bool #[source]: No description.

Methods

open_review_reasons() -> list[str] #[source]: No description.

item(rubric_id: str) -> RubricItemResult | None #[source]: No description.

to_dict() -> dict[str, Any] #[source]: No description.

classmethod from_dict(data: dict[str, Any]) -> 'SubmissionResult' #[source]: No description.

class GradingProgress #[source]

dataclass

Snapshot pushed to the UI while grading runs (design.md section 7).

Fields

Name	Type	Default
`total`	`int`	`0`
`completed`	`int`	`0`
`successful`	`int`	`0`
`flagged`	`int`	`0`
`failed`	`int`	`0`
`current_student`	`str \| None`	`None`
`stage`	`str`	`'idle'`
`stages`	`dict[str, str]`	`field(default_factory=dict)`
`finished`	`bool`	`False`
`message`	`str`	`''`

Properties

property remaining: int #[source]: No description.

Methods

to_dict() -> dict[str, Any] #[source]: No description.

Functions

status_icon(status: str) -> str #[source]: No description.

status_color(status: str) -> str #[source]: No description.