haive.agents.common.models.grade.composite
==========================================

.. py:module:: haive.agents.common.models.grade.composite

.. autoapi-nested-parse::

   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
-------

.. autoapisummary::

   haive.agents.common.models.grade.composite.CompositeGrade


Module Contents
---------------

.. py:class:: CompositeGrade(/, **data)

   Bases: :py:obj:`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.

   .. attribute:: grades

      List of individual grades to combine

   .. attribute:: weights

      Optional weights for each grade (auto-normalized)

   .. attribute:: combination_method

      Method for combining grades

   .. attribute:: primary_grade_index

      Index of the primary/most important grade

   .. attribute:: consensus_threshold

      Threshold for consensus analysis

   .. rubric:: Example

   .. code-block:: python

       # 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.


   .. py:method:: create_consensus_grade(grades, justification, consensus_threshold = 0.8, **kwargs)
      :classmethod:


      Create a CompositeGrade focused on consensus building.

      :param grades: List of Grade instances to combine
      :param justification: Overall justification
      :param consensus_threshold: Threshold for consensus detection
      :param \*\*kwargs: Additional parameters

      :returns: CompositeGrade configured for consensus analysis



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


      Create a CompositeGrade from a list of existing grades.

      :param grades: List of Grade instances to combine
      :param justification: Overall justification for the composite
      :param weights: Optional weights for each grade
      :param method: Combination method to use
      :param \*\*kwargs: Additional parameters

      :returns: CompositeGrade instance



   .. py:method:: get_consensus_analysis()

      Get detailed consensus analysis.

      :returns: Dictionary with consensus analysis information



   .. py:method:: get_grade_breakdown()

      Get detailed breakdown of individual grades.

      :returns: List of dictionaries with information about each grade



   .. py:method:: get_grade_statistics()

      Get statistical analysis of the individual grades.

      :returns: Dictionary containing statistical measures



   .. py:method:: 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



   .. py:method:: get_normalized_score_using_method(method)

      Get normalized score using a specific combination method.

      :param method: Combination method to use

      :returns: Normalized score using the specified method



   .. py:method:: get_normalized_weights()

      Get normalized weights that sum to 1.0.

      :returns: List of normalized weights (equal weights if none provided)



   .. py:method:: get_outlier_grades(threshold = 0.3)

      Identify grades that are outliers compared to the group.

      :param threshold: Deviation threshold for considering a grade an outlier

      :returns: List of indices of grades that are outliers



   .. py:method:: has_consensus()

      Check if there's consensus among the individual grades.

      :returns: True if the variance in normalized scores is below consensus threshold



   .. py:method:: is_passing(threshold = None)

      Determine if the composite grade represents a passing score.

      :param threshold: 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



   .. py:method:: to_display_string()

      Convert grade to a human-readable display string.

      :returns: Formatted string representation of the composite grade



   .. py:method:: validate_combination_method(v)
      :classmethod:


      Validate that combination method is supported.

      :param v: Combination method string

      :returns: Validated combination method

      :raises ValueError: If combination method is not supported



   .. py:method:: validate_grade_value(value)

      Validate that a value represents valid composite grade data.

      :param value: The value to validate (should be list of grades)

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



   .. py:method:: 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