agents.common.models.grade.letter_grade¶

Letter grading model for traditional A-F evaluations.

This module implements a traditional letter grading system with support for plus/minus modifiers and customizable grading scales.

Classes¶

`LetterGrade`	Letter grading model for traditional A-F evaluations.
`LetterValue`	Valid letter grade values.

Module Contents¶

class agents.common.models.grade.letter_grade.LetterGrade(/, **data)¶

Bases: haive.agents.common.models.grade.base.Grade

Letter grading model for traditional A-F evaluations.

This grade model represents traditional letter grades with optional plus/minus modifiers. Includes conversion utilities and customizable grading scales.

Parameters:: data (Any)

value¶: The letter grade value (A+ to F)

grade_type¶: Always GradeType.LETTER

gpa_scale¶: GPA scale to use (4.0 or 5.0, default 4.0)

passing_grade¶: Minimum letter grade considered passing (default C-)

Example

grade = LetterGrade(
value="B+",
justification="Strong understanding with minor gaps in analysis",
gpa_scale=4.0
)

# Using enum value
grade = LetterGrade(
value=LetterValue.A_MINUS,
justification="Excellent work with room for improvement"
)

# Custom passing threshold
grade = LetterGrade(
value="C",
passing_grade="C",  # C is passing instead of default C-
justification="Meets basic requirements"
)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

classmethod convert_to_letter_value(v)¶

Convert string or other representations to LetterValue.

Parameters:: v (Any) – Value to convert to LetterValue
Returns:: LetterValue enum instance
Raises:: ValueError – If the value cannot be converted to a valid letter grade
Return type:: LetterValue

classmethod from_percentage(percentage, justification, gpa_scale=4.0, **kwargs)¶

Create a LetterGrade from a percentage score.

Parameters:

percentage (float) – Percentage score (0-100)
justification (str) – Explanation for the grade
gpa_scale (float) – GPA scale to use
**kwargs – Additional parameters for the grade

Returns:

LetterGrade instance corresponding to the percentage

Raises:

ValueError – If percentage is outside valid range

Return type:

LetterGrade

get_gpa_points()¶

Get GPA points for this letter grade.

Returns:: GPA points based on the configured scale
Return type:: float

get_letter_quality_description()¶

Get a descriptive quality label for the letter grade.

Returns:: String describing the quality level of the grade
Return type:: str

get_normalized_score()¶

Get the grade as a normalized score between 0.0 and 1.0.

Uses standard percentage equivalents for letter grades.

Returns:: Normalized score based on letter grade
Return type:: float

is_passing(threshold=None)¶

Determine if the grade represents a passing score.

Parameters:: threshold (str | None) – Custom passing threshold as letter grade string. If None, uses instance passing_grade
Returns:: True if the grade meets or exceeds the passing threshold
Return type:: bool

to_display_string()¶

Convert grade to a human-readable display string.

Returns:: Formatted string representation of the letter grade
Return type:: str

classmethod validate_gpa_scale(v)¶

Validate GPA scale is reasonable.

Parameters:: v (float) – GPA scale value
Returns:: Validated GPA scale
Raises:: ValueError – If GPA scale is not reasonable
Return type:: float

validate_grade_value(value)¶

Validate that a value can be converted to a letter grade.

Parameters:: value (Any) – The value to validate
Returns:: True if the value can be converted to LetterValue, False otherwise
Return type:: bool

class agents.common.models.grade.letter_grade.LetterValue¶

Bases: str, enum.Enum

Valid letter grade values.

A_PLUS¶: Exceptional performance (A+)

A¶: Excellent performance (A)

A_MINUS¶: Very good performance (A-)

B_PLUS¶: Good performance (B+)

B¶: Satisfactory performance (B)

B_MINUS¶: Below satisfactory (B-)

C_PLUS¶: Acceptable performance (C+)

C¶: Minimally acceptable (C)

C_MINUS¶: Below acceptable (C-)

D_PLUS¶: Poor performance (D+)

D¶: Very poor performance (D)

D_MINUS¶: Extremely poor (D-)

F¶: Failing performance (F)

Initialize self. See help(type(self)) for accurate signature.