haive.agents.common.models.grade.letter_grade
=============================================

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

.. autoapi-nested-parse::

   Letter grading model for traditional A-F evaluations.

   This module implements a traditional letter grading system with support
   for plus/minus modifiers and customizable grading scales.



Classes
-------

.. autoapisummary::

   haive.agents.common.models.grade.letter_grade.LetterGrade
   haive.agents.common.models.grade.letter_grade.LetterValue


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

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

   Bases: :py:obj:`haive.agents.common.models.grade.base.Grade`


   Letter grading model for traditional A-F evaluations.

   This grade model represents traditional letter grades with optional
   plus/minus modifiers. Includes conversion utilities and customizable
   grading scales.

   .. attribute:: value

      The letter grade value (A+ to F)

   .. attribute:: grade_type

      Always GradeType.LETTER

   .. attribute:: gpa_scale

      GPA scale to use (4.0 or 5.0, default 4.0)

   .. attribute:: passing_grade

      Minimum letter grade considered passing (default C-)

   .. rubric:: Example

   .. code-block:: python

       grade = LetterGrade(
       value="B+",
       justification="Strong understanding with minor gaps in analysis",
       gpa_scale=4.0
       )

       # Using enum value
       grade = LetterGrade(
       value=LetterValue.A_MINUS,
       justification="Excellent work with room for improvement"
       )

       # Custom passing threshold
       grade = LetterGrade(
       value="C",
       passing_grade="C",  # C is passing instead of default C-
       justification="Meets basic requirements"
       )

   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:: convert_to_letter_value(v)
      :classmethod:


      Convert string or other representations to LetterValue.

      :param v: Value to convert to LetterValue

      :returns: LetterValue enum instance

      :raises ValueError: If the value cannot be converted to a valid letter grade



   .. py:method:: from_percentage(percentage, justification, gpa_scale = 4.0, **kwargs)
      :classmethod:


      Create a LetterGrade from a percentage score.

      :param percentage: Percentage score (0-100)
      :param justification: Explanation for the grade
      :param gpa_scale: GPA scale to use
      :param \*\*kwargs: Additional parameters for the grade

      :returns: LetterGrade instance corresponding to the percentage

      :raises ValueError: If percentage is outside valid range



   .. py:method:: get_gpa_points()

      Get GPA points for this letter grade.

      :returns: GPA points based on the configured scale



   .. py:method:: get_letter_quality_description()

      Get a descriptive quality label for the letter grade.

      :returns: String describing the quality level of the grade



   .. py:method:: get_normalized_score()

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

      Uses standard percentage equivalents for letter grades.

      :returns: Normalized score based on letter grade



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

      Determine if the grade represents a passing score.

      :param threshold: Custom passing threshold as letter grade string.
                        If None, uses instance passing_grade

      :returns: True if the grade meets or exceeds the passing threshold



   .. py:method:: to_display_string()

      Convert grade to a human-readable display string.

      :returns: Formatted string representation of the letter grade



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


      Validate GPA scale is reasonable.

      :param v: GPA scale value

      :returns: Validated GPA scale

      :raises ValueError: If GPA scale is not reasonable



   .. py:method:: validate_grade_value(value)

      Validate that a value can be converted to a letter grade.

      :param value: The value to validate

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



.. py:class:: LetterValue

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Valid letter grade values.

   .. attribute:: A_PLUS

      Exceptional performance (A+)

   .. attribute:: A

      Excellent performance (A)

   .. attribute:: A_MINUS

      Very good performance (A-)

   .. attribute:: B_PLUS

      Good performance (B+)

   .. attribute:: B

      Satisfactory performance (B)

   .. attribute:: B_MINUS

      Below satisfactory (B-)

   .. attribute:: C_PLUS

      Acceptable performance (C+)

   .. attribute:: C

      Minimally acceptable (C)

   .. attribute:: C_MINUS

      Below acceptable (C-)

   .. attribute:: D_PLUS

      Poor performance (D+)

   .. attribute:: D

      Very poor performance (D)

   .. attribute:: D_MINUS

      Extremely poor (D-)

   .. attribute:: F

      Failing performance (F)

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