haive.agents.common.models.grade.numeric
========================================

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

.. autoapi-nested-parse::

   Numeric grading models for score-based evaluations.

   This module implements numeric grading systems including general numeric
   scores and percentage-based grading.



Classes
-------

.. autoapisummary::

   haive.agents.common.models.grade.numeric.NumericGrade
   haive.agents.common.models.grade.numeric.PercentageGrade


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

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

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


   Numeric grading model for score-based evaluations.

   This grade model represents numeric scores within a configurable range,
   such as 0-10, 1-5, 0-100, etc.

   .. attribute:: value

      The numeric score value

   .. attribute:: min_value

      Minimum possible score (default 0)

   .. attribute:: max_value

      Maximum possible score (default 10)

   .. attribute:: passing_threshold

      Minimum score considered passing (default 60% of range)

   .. rubric:: Example

   .. code-block:: python

       # 0-10 scale
       grade = NumericGrade(
       value=8.5,
       min_value=0,
       max_value=10,
       justification="Strong performance with minor areas for improvement"
       )

       # 1-5 scale
       grade = NumericGrade(
       value=4,
       min_value=1,
       max_value=5,
       passing_threshold=3,
       justification="Above average quality"
       )

       # Custom range
       grade = NumericGrade(
       value=850,
       min_value=200,
       max_value=800,  # This will raise an error - value exceeds max
       justification="SAT score"
       )

   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:: distance_from_threshold(threshold = None)

      Calculate distance from passing threshold.

      :param threshold: Custom threshold to use. If None, uses instance threshold

      :returns: Positive value if above threshold, negative if below



   .. py:method:: get_letter_equivalent()

      Get an approximate letter grade equivalent.

      Uses standard grading scale based on percentage:
      A: 90-100%, B: 80-89%, C: 70-79%, D: 60-69%, F: <60%

      :returns: Letter grade string (A, B, C, D, F)



   .. py:method:: get_normalized_score()

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

      :returns: Normalized score calculated as (value - min) / (max - min)



   .. py:method:: get_percentage_score()

      Get the grade as a percentage (0-100).

      :returns: Percentage score (normalized score * 100)



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

      Determine if the grade represents a passing score.

      :param threshold: Custom threshold to use. If None, uses instance threshold
                        or 60% of range as default

      :returns: True if the score 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 numeric grade



   .. py:method:: validate_grade_value(value)

      Validate that a value is numeric and within range.

      :param value: The value to validate

      :returns: True if the value is valid, False otherwise



   .. py:method:: validate_score_range()

      Validate that the score is within the specified range.

      :returns: Self if validation passes

      :raises ValueError: If score is outside the valid range



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

   Bases: :py:obj:`NumericGrade`


   Percentage-based grading model (0-100%).

   A specialized numeric grade that's always in the 0-100 range,
   representing percentage scores.

   .. attribute:: value

      Percentage value (0-100)

   .. attribute:: min_value

      Always 0

   .. attribute:: max_value

      Always 100

   .. attribute:: passing_threshold

      Minimum percentage considered passing (default 60)

   .. rubric:: Example

   .. code-block:: python

       grade = PercentageGrade(
       value=87.5,
       justification="Excellent work with minor formatting issues",
       passing_threshold=70
       )

       # Automatically validates range
       bad_grade = PercentageGrade(
       value=105,  # This will raise an error
       justification="Invalid percentage"
       )

   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 grade as a normalized score between 0.0 and 1.0.

      For percentages, this is simply value / 100.

      :returns: Normalized score (percentage / 100)



   .. py:method:: get_percentage_score()

      Get the grade as a percentage (0-100).

      For PercentageGrade, this is just the value itself.

      :returns: The percentage value



   .. py:method:: to_display_string()

      Convert grade to a human-readable display string.

      :returns: Formatted string representation of the percentage grade



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


      Ensure max_value is always 100 for percentages.

      :param v: The max_value to validate

      :returns: Always returns 100



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


      Ensure min_value is always 0 for percentages.

      :param v: The min_value to validate

      :returns: Always returns 0