haive.agents.common.models.grade.base
=====================================

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

.. autoapi-nested-parse::

   Base classes for grade models.

   This module defines the fundamental abstractions for all grading models
   including the grade type enumeration and abstract base class.



Classes
-------

.. autoapisummary::

   haive.agents.common.models.grade.base.Grade
   haive.agents.common.models.grade.base.GradeType


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

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

   Bases: :py:obj:`pydantic.BaseModel`, :py:obj:`abc.ABC`


   Abstract base class for all grade models.

   This class provides the common interface and functionality that all
   grade models must implement. It includes metadata, validation,
   and utility methods.

   .. attribute:: grade_type

      The type of grade model

   .. attribute:: justification

      Explanation for the grade assigned

   .. attribute:: confidence

      Confidence level in the grade (0.0 to 1.0)

   .. attribute:: metadata

      Additional metadata about the grading

   .. attribute:: grader_id

      Identifier of the grader (agent, human, etc.)

   .. attribute:: timestamp

      When the grade was assigned

   .. rubric:: Example

   .. code-block:: python

       # This is an abstract class, use concrete implementations
       grade = BinaryGrade(
       value=True,
       justification="Response meets all criteria",
       confidence=0.95
       )

   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:: compare_to(other)

      Compare this grade to another grade.

      :param other: Another Grade instance to compare against

      :returns: Dictionary containing comparison information

      :raises TypeError: If other is not a Grade instance



   .. py:method:: get_grade_summary()

      Get a summary of the grade information.

      :returns: Dictionary containing key grade information for display



   .. py:method:: get_normalized_score()
      :abstractmethod:


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

      This method must be implemented by all concrete grade classes
      to provide a common way to compare grades across different types.

      :returns: A float between 0.0 and 1.0 representing the normalized grade



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


      Determine if the grade represents a passing score.

      :param threshold: Optional custom threshold for passing.
                        If None, uses grade type default.

      :returns: True if the grade is considered passing, False otherwise



   .. py:method:: to_display_string()

      Convert grade to a human-readable display string.

      :returns: Formatted string representation of the grade



   .. py:method:: validate_grade_value(value)

      Validate that a grade value is appropriate for this grade type.

      This method should be overridden by concrete classes to provide
      type-specific validation.

      :param value: The value to validate

      :returns: True if valid, False otherwise



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


      Validate that justification is meaningful.

      :param v: The justification string to validate

      :returns: The validated justification string

      :raises ValueError: If justification is empty, too short, or meaningless



   .. py:attribute:: model_config

      Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict].


.. py:class:: GradeType

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


   Types of grade models available.

   .. attribute:: BINARY

      Simple pass/fail or yes/no grading

   .. attribute:: NUMERIC

      Numeric scoring with configurable ranges

   .. attribute:: PERCENTAGE

      Percentage-based scoring (0-100%)

   .. attribute:: LETTER

      Traditional letter-based grading (A-F)

   .. attribute:: RUBRIC

      Multi-criteria rubric-based evaluation

   .. attribute:: QUALITATIVE

      Text-based qualitative assessment

   .. attribute:: SCALE

      Likert-scale or custom scale grading

   .. attribute:: COMPOSITE

      Combination of multiple grade types

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