CommentScore

Represents the comprehensive evaluation of a comment's quality and toxicity, under the site's tolerances.

Findings the site's tolerances accept have already been removed. health_items, health_score, overall_score and exceeds_tolerance report the comment's health under the tolerances sent with the request. See Comment Health.

Python
PHP
JSON

from respectify.schemas import CommentScore, HealthItemScore, LogicalFallacy, NegativeTonePhrase, ObjectionablePhrase

use Respectify\Schemas\CommentScore;
use Respectify\Schemas\LogicalFallacy;
use Respectify\Schemas\NegativeTonePhrase;
use Respectify\Schemas\ObjectionablePhrase;

Fields

logical_fallacies

List of logical fallacies found

Python
PHP
JSON

result.logical_fallacies: List[LogicalFallacy]

$result->logicalFallacies: LogicalFallacy[]

"logical_fallacies": [{
  "fallacy_name": "string",
  "quoted_logical_fallacy_example": "string",
  "explanation": "string",
  "suggested_rewrite": "string",
  "severity": 1
}, ...]

Each element is a LogicalFallacy object.

objectionable_phrases

List of objectionable phrases found

Python
PHP
JSON

result.objectionable_phrases: List[ObjectionablePhrase]

$result->objectionablePhrases: ObjectionablePhrase[]

"objectionable_phrases": [{
  "quoted_objectionable_phrase": "string",
  "explanation": "string",
  "suggested_rewrite": "string",
  "category": "string",
  "severity": 1
}, ...]

Each element is a ObjectionablePhrase object.

negative_tone_phrases

List of phrases with negative tone

Python
PHP
JSON

result.negative_tone_phrases: List[NegativeTonePhrase]

$result->negativeTonePhrases: NegativeTonePhrase[]

"negative_tone_phrases": [{
  "quoted_negative_tone_phrase": "string",
  "explanation": "string",
  "suggested_rewrite": "string",
  "category": "string",
  "severity": 1
}, ...]

Each element is a NegativeTonePhrase object.

appears_low_effort

Whether the comment appears to be low effort

Python
PHP
JSON

result.appears_low_effort: bool

$result->appearsLowEffort: bool

"appears_low_effort": true

overall_score

Comment health, 1-5: health_score rounded half up. The quality score alone is health_items["quality"].score. When every item is off (so there is no health_score), this is the quality rubric's score.

Responses from older servers, without health_items, give the quality score here.

Constraints: ge=1, le=5

Python
PHP
JSON

result.overall_score: int # 1-5

$result->overallScore: int

"overall_score": 1

toxicity_score

Toxicity score (0.0=not toxic, 1.0=highly toxic)

Constraints: ge=0.0, le=1.0

Python
PHP
JSON

result.toxicity_score: float # 0.0-1.0

$result->toxicityScore: float

"toxicity_score": 0.5

toxicity_explanation

Educational explanation of toxicity issues found

Python
PHP
JSON

result.toxicity_explanation: str

$result->toxicityExplanation: string

"toxicity_explanation": "string"

exceeds_tolerance

True when any comment health item scores below what the site accepts (any health_items entry has is_acceptable false), or the comment is severely toxic. Use this, rather than toxicity_score or overall_score alone, to decide whether to coach.

See exceeds_tolerance for exactly when it is set.

Python
PHP
JSON

result.exceeds_tolerance: bool

$result->exceedsTolerance: bool

"exceeds_tolerance": true

health_score

Comment health: the geometric mean of the quality score and the worst problem item's score, leaving out whichever is turned off. 1.0-5.0, to two decimal places.

Optional. Omitted from the JSON (not null) when every item is off, and absent from older servers' responses.

Constraints: ge=1.0, le=5.0

Python
PHP
JSON

result.health_score: Optional[float] # 1.0-5.0, None when every item is off

$result->healthScore: ?float

"health_score": 3.46

health_items

Each comment health item not turned off, by name: any of the nine categories and quality. Items set to off have no entry. Empty or absent in older servers' responses, so treat it as optional.

See Item scores for how each score is measured.

Python
PHP
JSON

result.health_items: Dict[str, HealthItemScore]

$result->healthItems: array<string, HealthItemScore>

"health_items": {
  "insult": { "score": 4, "minimum": 4, "is_acceptable": true },
  "quality": { "score": 3, "minimum": 3, "is_acceptable": true },
  ...
}

Each value is a HealthItemScore object.

tolerances

The tolerances this score was judged under

All ten items are present: the nine categories and quality. Each value is one of off, permissive, relaxed, standard, strict or zero_tolerance. Items the request did not name are standard. See Comment Health.

Python
PHP
JSON

result.tolerances: ModerationTolerances

$result->tolerances: ModerationTolerances

"tolerances": {
  "threat": "string",
  "identity_attack": "string",
  "sexual_content": "string",
  "harassment": "string",
  "insult": "string",
  "profanity": "string",
  "dismissive_tone": "string",
  "logical_fallacy": "string",
  "low_effort": "string",
  "quality": "string"
}

Sub-types

HealthItemScore

One comment health item: how the comment scored on it, and the lowest score the site accepts.

Python
PHP
JSON

Field	Type	Description
`score`	`int # 1-5`	5 means nothing found. For a category: minor finding 4, clear 3, severe 2, extreme 1. For quality: the quality score.
`minimum`	`int # 1-5`	The lowest score this item's level accepts
`is_acceptable`	`bool`	Whether `score` is at or above `minimum`

Field	Type	Description
`score`	`int`	5 means nothing found. For a category: minor finding 4, clear 3, severe 2, extreme 1. For quality: the quality score.
`minimum`	`int`	The lowest score this item's level accepts
`isAcceptable`	`bool`	Whether `score` is at or above `minimum`

{
  "score": 4,
  "minimum": 4,
  "is_acceptable": true
}

LogicalFallacy

Represents a logical fallacy identified in a comment.

Python
PHP
JSON

Field	Type	Description
`fallacy_name`	`str`	The name of the logical fallacy, e.g., 'straw man'
`quoted_logical_fallacy_example`	`str`	The part of the comment that contains the logical fallacy
`explanation`	`str`	Explanation of the fallacy and suggestions for improvement
`suggested_rewrite`	`str`	Suggested rewrite (only provided when comment appears good-faith; otherwise empty)
`severity`	`int # 1-4`	1 minor, 2 clear, 3 severe, 4 extreme

Field	Type	Description
`fallacyName`	`string`	The name of the logical fallacy, e.g., 'straw man'
`quotedLogicalFallacyExample`	`string`	The part of the comment that contains the logical fallacy
`explanation`	`string`	Explanation of the fallacy and suggestions for improvement
`suggestedRewrite`	`string`	Suggested rewrite (only provided when comment appears good-faith; otherwise empty)
`severity`	`int`	1 minor, 2 clear, 3 severe, 4 extreme

{
  "fallacy_name": "string",
  "quoted_logical_fallacy_example": "string",
  "explanation": "string",
  "suggested_rewrite": "string",
  "severity": 1
}

ObjectionablePhrase

Represents an objectionable phrase identified in a comment.

Python
PHP
JSON

Field	Type	Description
`quoted_objectionable_phrase`	`str`	The objectionable phrase found in the comment
`explanation`	`str`	Explanation of why this phrase is objectionable
`suggested_rewrite`	`str`	Suggested rewrite (only provided when comment appears good-faith; otherwise empty)
`category`	`ModerationCategory`	What kind of problem the phrase is: one of `threat`, `identity_attack`, `sexual_content`, `harassment`, `insult`, `profanity`, `dismissive_tone`
`severity`	`int # 1-4`	1 minor, 2 clear, 3 severe, 4 extreme

Field	Type	Description
`quotedObjectionablePhrase`	`string`	The objectionable phrase found in the comment
`explanation`	`string`	Explanation of why this phrase is objectionable
`suggestedRewrite`	`string`	Suggested rewrite (only provided when comment appears good-faith; otherwise empty)
`category`	`string`	What kind of problem the phrase is: one of the `ModerationCategory` constants for `threat`, `identity_attack`, `sexual_content`, `harassment`, `insult`, `profanity`, `dismissive_tone`
`severity`	`int`	1 minor, 2 clear, 3 severe, 4 extreme

{
  "quoted_objectionable_phrase": "string",
  "explanation": "string",
  "suggested_rewrite": "string",
  "category": "string",
  "severity": 1
}

NegativeTonePhrase

Represents a phrase with negative tone identified in a comment.

Python
PHP
JSON

Field	Type	Description
`quoted_negative_tone_phrase`	`str`	The phrase with negative tone
`explanation`	`str`	Explanation of the negative tone
`suggested_rewrite`	`str`	Suggested rewrite (only provided when comment appears good-faith; otherwise empty)
`category`	`ModerationCategory`	What kind of problem the phrase is: one of `threat`, `identity_attack`, `sexual_content`, `harassment`, `insult`, `profanity`, `dismissive_tone`
`severity`	`int # 1-4`	1 minor, 2 clear, 3 severe, 4 extreme

Field	Type	Description
`quotedNegativeTonePhrase`	`string`	The phrase with negative tone
`explanation`	`string`	Explanation of the negative tone
`suggestedRewrite`	`string`	Suggested rewrite (only provided when comment appears good-faith; otherwise empty)
`category`	`string`	What kind of problem the phrase is: one of the `ModerationCategory` constants for `threat`, `identity_attack`, `sexual_content`, `harassment`, `insult`, `profanity`, `dismissive_tone`
`severity`	`int`	1 minor, 2 clear, 3 severe, 4 extreme

{
  "quoted_negative_tone_phrase": "string",
  "explanation": "string",
  "suggested_rewrite": "string",
  "category": "string",
  "severity": 1
}

Fields​

logical_fallacies​

objectionable_phrases​

negative_tone_phrases​

appears_low_effort​

overall_score​

toxicity_score​

toxicity_explanation​

exceeds_tolerance​

health_score​

health_items​

tolerances​

Sub-types​

HealthItemScore​

LogicalFallacy​

ObjectionablePhrase​

NegativeTonePhrase​