haive.agents.common.models.grade.rubric ======================================= .. py:module:: haive.agents.common.models.grade.rubric .. autoapi-nested-parse:: Rubric grading model for multi-criteria evaluations. This module implements a rubric-based grading system that evaluates multiple criteria with individual scores and weights. Classes ------- .. autoapisummary:: haive.agents.common.models.grade.rubric.RubricCriterion haive.agents.common.models.grade.rubric.RubricGrade Module Contents --------------- .. py:class:: RubricCriterion(/, **data) Bases: :py:obj:`pydantic.BaseModel` Individual criterion within a rubric. Represents a single evaluation criterion with its own score, weight, and justification. .. attribute:: name Name of the criterion .. attribute:: score Score for this criterion .. attribute:: max_score Maximum possible score for this criterion .. attribute:: weight Relative weight of this criterion (default 1.0) .. attribute:: justification Explanation for the score given .. rubric:: Example .. code-block:: python criterion = RubricCriterion( name="Content Quality", score=8.5, max_score=10, weight=0.4, justification="Strong content with minor gaps in coverage" ) 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. .. py:method:: get_normalized_score() Get the criterion score as a normalized value (0.0 to 1.0). :returns: Normalized score (score / max_score) .. py:method:: get_percentage_score() Get the criterion score as a percentage. :returns: Percentage score (normalized score * 100) .. py:method:: get_weighted_max_score() Get the weighted maximum score for this criterion. :returns: Max score multiplied by weight .. py:method:: get_weighted_score() Get the weighted score for this criterion. :returns: Score multiplied by weight .. py:method:: validate_score_range(v, info) :classmethod: Validate that score is within valid range. :param v: The score value :param info: Validation context containing other field values :returns: Validated score :raises ValueError: If score is outside valid range .. py:method:: validate_score_within_max() Validate that score does not exceed max_score. :returns: Self if validation passes :raises ValueError: If score exceeds max_score .. py:class:: RubricGrade(/, **data) Bases: :py:obj:`haive.agents.common.models.grade.base.Grade` Rubric grading model for multi-criteria evaluations. This grade model evaluates multiple criteria, each with their own scores, weights, and justifications, then combines them into an overall grade. .. attribute:: criteria List of individual rubric criteria .. attribute:: grade_type Always GradeType.RUBRIC .. attribute:: overall_justification Overall summary justification .. rubric:: Example .. code-block:: python criteria = [ RubricCriterion( name="Content Quality", score=8.5, max_score=10, weight=0.4, justification="Strong content with comprehensive coverage" ), RubricCriterion( name="Organization", score=7.0, max_score=10, weight=0.3, justification="Good structure but some transitions unclear" ), RubricCriterion( name="Grammar", score=9.0, max_score=10, weight=0.3, justification="Excellent grammar with only minor errors" ) ] grade = RubricGrade( criteria=criteria, justification="Overall strong performance with room for improvement in organization" ) 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. .. py:method:: create_simple_rubric(criteria_scores, justification, max_score = 10.0, **kwargs) :classmethod: Create a simple rubric with equal weights. :param criteria_scores: Dict mapping criterion names to scores or score dicts :param justification: Overall justification :param max_score: Maximum score for all criteria (default 10.0) :param \*\*kwargs: Additional parameters for the grade :returns: RubricGrade instance with equal-weighted criteria .. rubric:: Example .. code-block:: python grade = RubricGrade.create_simple_rubric( criteria_scores={ "Content": 8.5, "Style": {"score": 7.0, "justification": "Good style overall"}, "Accuracy": 9.0 }, justification="Strong overall performance", max_score=10 ) .. py:method:: get_criteria_summary() Get a summary of all criteria performance. :returns: Dictionary mapping criterion names to their summary info .. py:method:: get_criterion_by_name(name) Get a specific criterion by name. :param name: Name of the criterion to find :returns: RubricCriterion if found, None otherwise .. py:method:: get_improvement_suggestions() Generate improvement suggestions based on weakest criteria. :returns: List of suggestions for improvement .. py:method:: get_max_weighted_score() Get the maximum possible weighted score. :returns: Sum of all weighted maximum scores .. py:method:: get_normalized_score() Get the overall grade as a normalized score between 0.0 and 1.0. Calculates weighted average of all criteria scores. :returns: Weighted normalized score across all criteria .. py:method:: get_raw_weighted_score() Get the total raw weighted score. :returns: Sum of all weighted scores .. py:method:: get_strongest_criteria(count = 3) Get the criteria with the highest normalized scores. :param count: Number of strongest criteria to return :returns: List of criteria sorted by normalized score (highest first) .. py:method:: get_weakest_criteria(count = 3) Get the criteria with the lowest normalized scores. :param count: Number of weakest criteria to return :returns: List of criteria sorted by normalized score (lowest first) .. py:method:: is_passing(threshold = None) Determine if the rubric grade represents a passing score. :param threshold: Custom threshold for passing (0.0 to 1.0). If None, uses 0.7 (70%) as default :returns: True if the overall score meets or exceeds the threshold .. py:method:: to_display_string() Convert grade to a human-readable display string. :returns: Formatted string representation of the rubric grade .. py:method:: validate_criteria_names_unique(v) :classmethod: Validate that all criterion names are unique. :param v: List of criteria to validate :returns: Validated criteria list :raises ValueError: If criterion names are not unique .. py:method:: validate_grade_value(value) Validate that a value represents valid rubric criteria. :param value: The value to validate (should be list of criteria) :returns: True if the value can be converted to valid criteria, False otherwise