agents.common.models.grade.qualitative¶

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¶

`QualitativeGrade`	Qualitative grading model for text-based evaluations.
`QualityLevel`	Quality levels for qualitative assessment.
`SentimentType`	Sentiment types for qualitative feedback.

Module Contents¶

class agents.common.models.grade.qualitative.QualitativeGrade(/, **data)¶

Bases: 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.

Parameters:: data (Any)

quality_level¶: Overall quality assessment

sentiment¶: Sentiment of the feedback

strengths¶: List of identified strengths

weaknesses¶: List of identified weaknesses

recommendations¶: List of improvement recommendations

detailed_feedback¶: Extended qualitative feedback

Example

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.

classmethod create_constructive_feedback(justification, strengths, weaknesses, recommendations, quality_level=QualityLevel.FAIR, **kwargs)¶

Create balanced constructive feedback.

Parameters:

justification (str) – Main justification
strengths (list[str]) – List of strengths
weaknesses (list[str]) – List of weaknesses
recommendations (list[str]) – List of improvement recommendations
quality_level (QualityLevel) – Quality level (default FAIR)
**kwargs – Additional parameters

Returns:

QualitativeGrade with balanced feedback

Return type:

QualitativeGrade

classmethod create_positive_feedback(justification, strengths, minor_improvements=None, quality_level=QualityLevel.GOOD, **kwargs)¶

Create predominantly positive qualitative feedback.

Parameters:

justification (str) – Main justification
strengths (list[str]) – List of strengths to highlight
minor_improvements (list[str] | None) – Optional minor areas for improvement
quality_level (QualityLevel) – Quality level (default GOOD)
**kwargs – Additional parameters

Returns:

QualitativeGrade with positive sentiment

Return type:

QualitativeGrade

generate_narrative_summary()¶

Generate a narrative summary of the qualitative assessment.

Returns:: Human-readable narrative summary
Return type:: str

get_feedback_summary()¶

Get a structured summary of all feedback.

Returns:: Dictionary containing organized feedback information
Return type:: dict[str, Any]

get_improvement_priority()¶

Get prioritized improvement recommendations.

Returns top weaknesses with corresponding recommendations.

Returns:: List of prioritized improvement items
Return type:: list[str]

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
Return type:: float

is_passing(threshold=None)¶

Determine if the grade represents a passing score.

Parameters:: threshold (float | None) – 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
Return type:: bool

to_display_string()¶

Convert grade to a human-readable display string.

Returns:: Formatted string representation of the qualitative grade
Return type:: str

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
Return type:: QualitativeGrade

classmethod validate_feedback_items(v)¶

Validate that feedback items are meaningful.

Parameters:: v (list[str]) – List of feedback items to validate
Returns:: Validated list of feedback items
Raises:: ValueError – If items are empty or too vague
Return type:: list[str]

validate_grade_value(value)¶

Validate that a value can be converted to a quality level.

Parameters:: value (Any) – The value to validate
Returns:: True if the value can be converted to QualityLevel, False otherwise
Return type:: bool

class agents.common.models.grade.qualitative.QualityLevel¶

Bases: str, enum.Enum

Quality levels for qualitative assessment.

EXCEPTIONAL¶: Outstanding quality, exceeds expectations

EXCELLENT¶: High quality, meets all expectations

GOOD¶: Satisfactory quality, meets most expectations

FAIR¶: Adequate quality, meets basic expectations

POOR¶: Below expectations, significant issues

UNACCEPTABLE¶: Does not meet minimum standards

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

class agents.common.models.grade.qualitative.SentimentType¶

Bases: str, enum.Enum

Sentiment types for qualitative feedback.

VERY_POSITIVE¶: Highly positive feedback

POSITIVE¶: Generally positive feedback

NEUTRAL¶: Balanced or neutral feedback

NEGATIVE¶: Generally negative feedback

VERY_NEGATIVE¶: Highly negative feedback

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