agents.common.models.grade.numeric¶

Numeric grading models for score-based evaluations.

This module implements numeric grading systems including general numeric scores and percentage-based grading.

Classes¶

`NumericGrade`	Numeric grading model for score-based evaluations.
`PercentageGrade`	Percentage-based grading model (0-100%).

Module Contents¶

class agents.common.models.grade.numeric.NumericGrade(/, **data)¶

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

Numeric grading model for score-based evaluations.

This grade model represents numeric scores within a configurable range, such as 0-10, 1-5, 0-100, etc.

Parameters:: data (Any)

value¶: The numeric score value

min_value¶: Minimum possible score (default 0)

max_value¶: Maximum possible score (default 10)

passing_threshold¶: Minimum score considered passing (default 60% of range)

Example

# 0-10 scale
grade = NumericGrade(
value=8.5,
min_value=0,
max_value=10,
justification="Strong performance with minor areas for improvement"
)

# 1-5 scale
grade = NumericGrade(
value=4,
min_value=1,
max_value=5,
passing_threshold=3,
justification="Above average quality"
)

# Custom range
grade = NumericGrade(
value=850,
min_value=200,
max_value=800,  # This will raise an error - value exceeds max
justification="SAT score"
)

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.

distance_from_threshold(threshold=None)¶

Calculate distance from passing threshold.

Parameters:: threshold (float | None) – Custom threshold to use. If None, uses instance threshold
Returns:: Positive value if above threshold, negative if below
Return type:: float

get_letter_equivalent()¶

Get an approximate letter grade equivalent.

Uses standard grading scale based on percentage: A: 90-100%, B: 80-89%, C: 70-79%, D: 60-69%, F: <60%

Returns:: Letter grade string (A, B, C, D, F)
Return type:: str

get_normalized_score()¶

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

Returns:: Normalized score calculated as (value - min) / (max - min)
Return type:: float

get_percentage_score()¶

Get the grade as a percentage (0-100).

Returns:: Percentage score (normalized score * 100)
Return type:: float

is_passing(threshold=None)¶

Determine if the grade represents a passing score.

Parameters:: threshold (float | None) – Custom threshold to use. If None, uses instance threshold or 60% of range as default
Returns:: True if the score 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 numeric grade
Return type:: str

validate_grade_value(value)¶

Validate that a value is numeric and within range.

Parameters:: value (Any) – The value to validate
Returns:: True if the value is valid, False otherwise
Return type:: bool

validate_score_range()¶

Validate that the score is within the specified range.

Returns:: Self if validation passes
Raises:: ValueError – If score is outside the valid range
Return type:: NumericGrade

class agents.common.models.grade.numeric.PercentageGrade(/, **data)¶

Bases: NumericGrade

Percentage-based grading model (0-100%).

A specialized numeric grade that’s always in the 0-100 range, representing percentage scores.

Parameters:: data (Any)

value¶: Percentage value (0-100)

min_value¶: Always 0

max_value¶: Always 100

passing_threshold¶: Minimum percentage considered passing (default 60)

Example

grade = PercentageGrade(
value=87.5,
justification="Excellent work with minor formatting issues",
passing_threshold=70
)

# Automatically validates range
bad_grade = PercentageGrade(
value=105,  # This will raise an error
justification="Invalid percentage"
)

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.

get_normalized_score()¶

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

For percentages, this is simply value / 100.

Returns:: Normalized score (percentage / 100)
Return type:: float

get_percentage_score()¶

Get the grade as a percentage (0-100).

For PercentageGrade, this is just the value itself.

Returns:: The percentage value
Return type:: float

to_display_string()¶

Convert grade to a human-readable display string.

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

classmethod validate_max_value(v)¶

Ensure max_value is always 100 for percentages.

Parameters:: v (int | float) – The max_value to validate
Returns:: Always returns 100
Return type:: int | float

classmethod validate_min_value(v)¶

Ensure min_value is always 0 for percentages.

Parameters:: v (int | float) – The min_value to validate
Returns:: Always returns 0
Return type:: int | float