haive.agents.common.models.grade.qualitative ============================================ .. py:module:: haive.agents.common.models.grade.qualitative .. autoapi-nested-parse:: Qualitative grading model for text-based evaluations. This module implements a qualitative grading system that provides text-based assessments with sentiment analysis and quality indicators. Classes ------- .. autoapisummary:: haive.agents.common.models.grade.qualitative.QualitativeGrade haive.agents.common.models.grade.qualitative.QualityLevel haive.agents.common.models.grade.qualitative.SentimentType Module Contents --------------- .. py:class:: QualitativeGrade(/, **data) Bases: :py:obj:`haive.agents.common.models.grade.base.Grade` Qualitative grading model for text-based evaluations. This grade model provides detailed text-based assessments with quality levels, sentiment analysis, and structured feedback including strengths, weaknesses, and recommendations. .. attribute:: quality_level Overall quality assessment .. attribute:: sentiment Sentiment of the feedback .. attribute:: strengths List of identified strengths .. attribute:: weaknesses List of identified weaknesses .. attribute:: recommendations List of improvement recommendations .. attribute:: detailed_feedback Extended qualitative feedback .. rubric:: Example .. code-block:: python grade = QualitativeGrade( quality_level=QualityLevel.GOOD, sentiment=SentimentType.POSITIVE, strengths=[ "Clear logical structure", "Strong supporting evidence", "Engaging writing style" ], weaknesses=[ "Minor grammatical errors", "Could use more varied sentence structure" ], recommendations=[ "Proofread for grammatical accuracy", "Vary sentence length and structure for better flow" ], justification="Well-written piece with strong content but needs polish", detailed_feedback="This work demonstrates a solid understanding..." ) 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_constructive_feedback(justification, strengths, weaknesses, recommendations, quality_level = QualityLevel.FAIR, **kwargs) :classmethod: Create balanced constructive feedback. :param justification: Main justification :param strengths: List of strengths :param weaknesses: List of weaknesses :param recommendations: List of improvement recommendations :param quality_level: Quality level (default FAIR) :param \*\*kwargs: Additional parameters :returns: QualitativeGrade with balanced feedback .. py:method:: create_positive_feedback(justification, strengths, minor_improvements = None, quality_level = QualityLevel.GOOD, **kwargs) :classmethod: Create predominantly positive qualitative feedback. :param justification: Main justification :param strengths: List of strengths to highlight :param minor_improvements: Optional minor areas for improvement :param quality_level: Quality level (default GOOD) :param \*\*kwargs: Additional parameters :returns: QualitativeGrade with positive sentiment .. py:method:: generate_narrative_summary() Generate a narrative summary of the qualitative assessment. :returns: Human-readable narrative summary .. py:method:: get_feedback_summary() Get a structured summary of all feedback. :returns: Dictionary containing organized feedback information .. py:method:: get_improvement_priority() Get prioritized improvement recommendations. Returns top weaknesses with corresponding recommendations. :returns: List of prioritized improvement items .. py:method:: get_normalized_score() Get the grade as a normalized score between 0.0 and 1.0. Based on quality level mapping to numeric equivalents. :returns: Normalized score based on quality level .. py:method:: is_passing(threshold = None) Determine if the grade represents a passing score. :param threshold: Custom threshold for passing (0.0 to 1.0). If None, uses 0.6 (equivalent to "fair" quality) :returns: True if the quality level meets or exceeds the threshold .. py:method:: to_display_string() Convert grade to a human-readable display string. :returns: Formatted string representation of the qualitative grade .. py:method:: validate_feedback_consistency() Validate that feedback is consistent with quality level. :returns: Self if validation passes :raises ValueError: If feedback is inconsistent with quality level .. py:method:: validate_feedback_items(v) :classmethod: Validate that feedback items are meaningful. :param v: List of feedback items to validate :returns: Validated list of feedback items :raises ValueError: If items are empty or too vague .. py:method:: validate_grade_value(value) Validate that a value can be converted to a quality level. :param value: The value to validate :returns: True if the value can be converted to QualityLevel, False otherwise .. py:class:: QualityLevel Bases: :py:obj:`str`, :py:obj:`enum.Enum` Quality levels for qualitative assessment. .. attribute:: EXCEPTIONAL Outstanding quality, exceeds expectations .. attribute:: EXCELLENT High quality, meets all expectations .. attribute:: GOOD Satisfactory quality, meets most expectations .. attribute:: FAIR Adequate quality, meets basic expectations .. attribute:: POOR Below expectations, significant issues .. attribute:: UNACCEPTABLE Does not meet minimum standards Initialize self. See help(type(self)) for accurate signature. .. py:class:: SentimentType Bases: :py:obj:`str`, :py:obj:`enum.Enum` Sentiment types for qualitative feedback. .. attribute:: VERY_POSITIVE Highly positive feedback .. attribute:: POSITIVE Generally positive feedback .. attribute:: NEUTRAL Balanced or neutral feedback .. attribute:: NEGATIVE Generally negative feedback .. attribute:: VERY_NEGATIVE Highly negative feedback Initialize self. See help(type(self)) for accurate signature.