agents.common.models.grade.composite

Composite grading model for combining multiple grade types.

This module implements a composite grading system that combines multiple different grade types into a single comprehensive evaluation.

Classes

CompositeGrade

Composite grading model for combining multiple grade types.

Module Contents

class agents.common.models.grade.composite.CompositeGrade(/, **data)

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

Composite grading model for combining multiple grade types.

This grade model combines multiple individual grades of different types into a single comprehensive assessment. It supports weighted averaging, statistical analysis, and consensus building across different grading approaches.

Parameters:

data (Any)

grades

List of individual grades to combine

weights

Optional weights for each grade (auto-normalized)

combination_method

Method for combining grades

primary_grade_index

Index of the primary/most important grade

consensus_threshold

Threshold for consensus analysis

Example

# Individual grades
binary_grade = BinaryGrade(value=True, justification="Meets requirements")
numeric_grade = NumericGrade(value=8.5, max_value=10, justification="High quality work")
letter_grade = LetterGrade(value="B+", justification="Good performance overall")

# Composite grade
composite = CompositeGrade(
grades=[binary_grade, numeric_grade, letter_grade],
weights=[0.2, 0.5, 0.3],  # Different importance levels
combination_method="weighted_average",
justification="Combined assessment across multiple criteria"
)

# Equal weight composite
composite_equal = CompositeGrade(
grades=[binary_grade, numeric_grade, letter_grade],
combination_method="simple_average",
justification="Balanced multi-perspective evaluation"
)

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_consensus_grade(grades, justification, consensus_threshold=0.8, **kwargs)

Create a CompositeGrade focused on consensus building.

Parameters:

  • grades (list[haive.agents.common.models.grade.base.Grade]) – List of Grade instances to combine

  • justification (str) – Overall justification

  • consensus_threshold (float) – Threshold for consensus detection

  • **kwargs – Additional parameters

Returns:

CompositeGrade configured for consensus analysis

Return type:

CompositeGrade

classmethod create_from_grades(grades, justification, weights=None, method='weighted_average', **kwargs)

Create a CompositeGrade from a list of existing grades.

Parameters:

  • grades (list[haive.agents.common.models.grade.base.Grade]) – List of Grade instances to combine

  • justification (str) – Overall justification for the composite

  • weights (list[float] | None) – Optional weights for each grade

  • method (str) – Combination method to use

  • **kwargs – Additional parameters

Returns:

CompositeGrade instance

Return type:

CompositeGrade

get_consensus_analysis()

Get detailed consensus analysis.

Returns:

Dictionary with consensus analysis information

Return type:

dict[str, Any]

get_grade_breakdown()

Get detailed breakdown of individual grades.

Returns:

List of dictionaries with information about each grade

Return type:

list[dict[str, Any]]

get_grade_statistics()

Get statistical analysis of the individual grades.

Returns:

Dictionary containing statistical measures

Return type:

dict[str, float]

get_normalized_score()

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

Uses the specified combination method to compute the final score.

Returns:

Combined normalized score across all grades

Return type:

float

get_normalized_score_using_method(method)

Get normalized score using a specific combination method.

Parameters:

method (str) – Combination method to use

Returns:

Normalized score using the specified method

Return type:

float

get_normalized_weights()

Get normalized weights that sum to 1.0.

Returns:

List of normalized weights (equal weights if none provided)

Return type:

list[float]

get_outlier_grades(threshold=0.3)

Identify grades that are outliers compared to the group.

Parameters:

threshold (float) – Deviation threshold for considering a grade an outlier

Returns:

List of indices of grades that are outliers

Return type:

list[int]

has_consensus()

Check if there’s consensus among the individual grades.

Returns:

True if the variance in normalized scores is below consensus threshold

Return type:

bool

is_passing(threshold=None)

Determine if the composite grade represents a passing score.

Parameters:

threshold (float | None) – Custom threshold for passing (0.0 to 1.0). If None, uses 0.6 as default

Returns:

True if the composite score meets or exceeds the threshold

Return type:

bool

to_display_string()

Convert grade to a human-readable display string.

Returns:

Formatted string representation of the composite grade

Return type:

str

classmethod validate_combination_method(v)

Validate that combination method is supported.

Parameters:

v (str) – Combination method string

Returns:

Validated combination method

Raises:

ValueError – If combination method is not supported

Return type:

str

validate_grade_value(value)

Validate that a value represents valid composite grade data.

Parameters:

value (Any) – The value to validate (should be list of grades)

Returns:

True if the value can be converted to valid grades, False otherwise

Return type:

bool

validate_weights_and_indices()

Validate weights match grades count and indices are valid.

Returns:

Self if validation passes

Raises:

ValueError – If weights or indices are invalid

Return type:

CompositeGrade