agents.common.models.grade.scale¶

Scale grading model for Likert-style evaluations.

This module implements scale-based grading systems including Likert scales, satisfaction ratings, and custom ordinal scales.

Classes¶

`LikertScale`	Standard 5-point Likert scale values.
`SatisfactionScale`	Standard satisfaction rating scale.
`ScaleGrade`	Scale grading model for Likert-style evaluations.

Module Contents¶

class agents.common.models.grade.scale.LikertScale¶

Bases: str, enum.Enum

Standard 5-point Likert scale values.

STRONGLY_DISAGREE¶: Strongly disagree (1)

DISAGREE¶: Disagree (2)

NEUTRAL¶: Neither agree nor disagree (3)

AGREE¶: Agree (4)

STRONGLY_AGREE¶: Strongly agree (5)

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

class agents.common.models.grade.scale.SatisfactionScale¶

Bases: str, enum.Enum

Standard satisfaction rating scale.

VERY_DISSATISFIED¶: Very dissatisfied (1)

DISSATISFIED¶: Dissatisfied (2)

NEUTRAL¶: Neutral (3)

SATISFIED¶: Satisfied (4)

VERY_SATISFIED¶: Very satisfied (5)

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

class agents.common.models.grade.scale.ScaleGrade(/, **data)¶

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

Scale grading model for Likert-style evaluations.

This grade model represents ordinal scale ratings such as Likert scales, satisfaction ratings, or custom scales with labeled points.

Parameters:: data (Any)

scale_value¶: The selected scale value

scale_labels¶: List of scale labels in order from lowest to highest

scale_type¶: Optional scale type identifier

numeric_value¶: Numeric equivalent of the scale position

Example

# Using predefined Likert scale
grade = ScaleGrade(
scale_value="agree",
scale_labels=["strongly_disagree", "disagree", "neutral", "agree", "strongly_agree"],
scale_type="likert_5",
justification="Response shows good understanding with minor reservations"
)

# Custom satisfaction scale
grade = ScaleGrade(
scale_value="satisfied",
scale_labels=["very_dissatisfied", "dissatisfied", "neutral", "satisfied", "very_satisfied"],
scale_type="satisfaction",
justification="User feedback indicates satisfaction with minor issues"
)

# Custom numeric scale with labels
grade = ScaleGrade(
scale_value="good",
scale_labels=["poor", "fair", "good", "very_good", "excellent"],
scale_type="quality_5",
justification="Quality meets expectations"
)

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 create_likert_5(value, justification, **kwargs)¶

Create a 5-point Likert scale grade.

Parameters:

value (str | LikertScale) – Likert scale value
justification (str) – Explanation for the rating
**kwargs – Additional parameters

Returns:

ScaleGrade configured as 5-point Likert scale

Return type:

ScaleGrade

classmethod create_numeric_scale(value, min_value=1, max_value=5, justification='', **kwargs)¶

Create a numeric scale grade.

Parameters:

value (int) – Numeric value selected
min_value (int) – Minimum value of the scale
max_value (int) – Maximum value of the scale
justification (str) – Explanation for the rating
**kwargs – Additional parameters

Returns:

ScaleGrade configured as numeric scale

Return type:

ScaleGrade

classmethod create_quality_scale(value, justification, scale_size=5, **kwargs)¶

Create a quality assessment scale grade.

Parameters:

value (str) – Quality level selected
justification (str) – Explanation for the rating
scale_size (int) – Size of the quality scale (3, 4, or 5)
**kwargs – Additional parameters

Returns:

ScaleGrade configured as quality scale

Return type:

ScaleGrade

classmethod create_satisfaction_5(value, justification, **kwargs)¶

Create a 5-point satisfaction scale grade.

Parameters:

value (str | SatisfactionScale) – Satisfaction scale value
justification (str) – Explanation for the rating
**kwargs – Additional parameters

Returns:

ScaleGrade configured as 5-point satisfaction scale

Return type:

ScaleGrade

distance_from_neutral()¶

Calculate distance from the neutral/middle point of the scale.

Returns:: Signed distance from neutral (negative = below, positive = above)
Return type:: float

get_adjacent_values()¶

Get the adjacent scale values (one above and one below).

Returns:: Dictionary with ‘lower’ and ‘higher’ adjacent values
Return type:: dict[str, str | None]

get_descriptive_assessment()¶

Get a descriptive assessment based on scale position.

Returns:: Descriptive string based on position in scale
Return type:: str

get_normalized_score()¶

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

Based on position within the scale range.

Returns:: Normalized score (position - 1) / (max_position - 1)
Return type:: float

get_scale_percentage()¶

Get the scale position as a percentage.

Returns:: Percentage representing position in scale (0-100)
Return type:: float

get_scale_position()¶

Get the 1-indexed position of the value in the scale.

Returns:: Position of the selected value (1 = lowest, max = highest)
Return type:: int

is_bottom_tier(bottom_percent=0.3)¶

Check if the grade is in the bottom tier of the scale.

Parameters:: bottom_percent (float) – What percentage of the scale constitutes “bottom tier”
Returns:: True if the grade is in the bottom tier
Return type:: bool

is_passing(threshold=None)¶

Determine if the scale grade represents a passing score.

Parameters:: threshold (float | None) – Custom threshold (0.0 to 1.0). If None, uses the middle point of the scale as threshold
Returns:: True if the scale position meets or exceeds the threshold
Return type:: bool

is_top_tier(top_percent=0.3)¶

Check if the grade is in the top tier of the scale.

Parameters:: top_percent (float) – What percentage of the scale constitutes “top tier”
Returns:: True if the grade is in the top tier
Return type:: bool

to_display_string()¶

Convert grade to a human-readable display string.

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

validate_grade_value(value)¶

Validate that a value exists in the scale labels.

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

classmethod validate_scale_labels_unique(v)¶

Validate that all scale labels are unique.

Parameters:: v (list[str]) – List of scale labels to validate
Returns:: Validated scale labels list
Raises:: ValueError – If scale labels are not unique
Return type:: list[str]

validate_scale_value_and_set_numeric()¶

Validate scale_value is in scale_labels and set numeric_value.

Returns:: Self with numeric_value set
Raises:: ValueError – If scale_value is not in scale_labels
Return type:: ScaleGrade