Skip to content

AccessibilityGuard

Checks AI output readability, jargon density, and structural organization. Inspired by Collective Constitutional AI finding that the public prioritized accessibility in AI outputs. Uses Flesch-Kincaid grade level scoring, domain-specific jargon detection across 4 domains (~100 terms), and structure analysis.

Professional License Required

AccessibilityGuard requires a Professional or Enterprise license. See Licensing for details.

Executive Summary

The Problem

AI outputs frequently use unnecessarily complex language, domain-specific jargon, and poor structural organization. This makes AI responses inaccessible to general audiences, violates plain language principles, and reduces trust and utility.

Accessibility Metrics

Metric What It Measures Standard
Flesch-Kincaid Grade Level US grade equivalent of text Target: Grade 8.0
Flesch Reading Ease Readability score (0-100) Target: 60-70
Jargon Density Ratio of jargon to total words Max: 5%
Structure Score Headings + lists for long text Required > 300 words
Sentence Length Average words per sentence Max: 20 words

Industry Context

The Collective Constitutional AI study (Anthropic, 2023) found that 1,000 participants across 38,252 votes strongly prioritized accessibility and understandable language. WCAG 2.2 Guideline 3.1 recommends lower secondary education level. The US Plain Language Act (2010) requires clear, concise government communication.

Sources: Collective Constitutional AI (Anthropic, 2023), Flesch-Kincaid (Kincaid et al., 1975), WCAG 2.2, Plain Language Act (2010), AHRQ Health Literacy, CDC Clear Communication Index

Detection Categories

1. Reading Level Too High

Flesch-Kincaid grade level exceeds the target (default: Grade 8.0):

Grade 5:  "The cat sat on the mat." (simple)
Grade 12: "The implementation necessitates comprehensive understanding." (complex)
Grade 16+: Academic/professional jargon-heavy text

2. High Jargon Density

Too many technical or domain-specific terms relative to total word count:

Domain Example Terms Plain Alternatives
Medical hypertension, tachycardia, prophylaxis high blood pressure, fast heart rate, prevention
Legal fiduciary, adjudication, indemnification trust-based responsibility, formal judgment, protection from liability
Technical idempotent, serialization, polymorphism can be repeated safely, converting to storable format, many forms of behavior
Financial amortization, collateral, derivative spreading cost over time, asset pledged as security, contract based on other assets

3. Missing Structure

Long text (>300 words) without headings or lists, making it difficult to scan and navigate.

4. Long Sentences

Average sentence length exceeds 20 words, reducing comprehension.

5. Excessive Passive Voice

Overuse of passive constructions that reduce clarity.

6. No Plain Alternative

Jargon terms used without providing a plain-language equivalent in the text.

Jargon Dictionary

AccessibilityGuard includes ~100 jargon terms across 4 domains, each with a plain-language alternative:

Domain Terms Examples
Medical ~25 contraindicated → not recommended, edema → swelling
Legal ~25 habeas corpus → right to challenge detention, tort → wrongful act in law
Technical ~25 deprecated → no longer recommended, latency → delay time
Financial ~25 liquidity → ease of converting to cash, volatility → price fluctuation

All jargon detection uses AhoCorasick for efficient multi-pattern matching.

Developer Guide

Basic Usage

use oxide_wellbeing::accessibility::AccessibilityGuard;

let guard = AccessibilityGuard::new("accessibility");

let result = guard.check(
    "The patient's hypertension and tachycardia suggest \
     a possible myocardial infarction."
);

if result.issues_detected {
    println!("Score: {:.2}", result.accessibility_score);
    for rec in &result.recommendations {
        println!("Recommendation: {}", rec);
    }
    for (jargon, plain) in &result.alternatives {
        println!("{} → {}", jargon, plain);
    }
}

from oxideshield import accessibility_guard, AccessibilityGuard

# Using convenience function
guard = accessibility_guard()

# Check a response
result = guard.check("The implementation necessitates comprehensive understanding.")
if not result.passed:
    print(f"Accessibility issues detected")

Readability Analysis

use oxide_wellbeing::accessibility::{AccessibilityGuard, flesch_kincaid_grade, flesch_reading_ease};

// Standalone readability functions
let grade = flesch_kincaid_grade("The cat sat on the mat.");
let ease = flesch_reading_ease("The cat sat on the mat.");

// Full metrics from guard
let guard = AccessibilityGuard::new("test");
let metrics = guard.analyze_readability("Your text here.");
println!("Grade: {:.1}", metrics.flesch_kincaid_grade);
println!("Ease: {:.1}", metrics.flesch_reading_ease);
println!("Complex words: {:.1}%", metrics.complex_word_percentage);

Custom Configuration

use oxide_wellbeing::accessibility::AccessibilityGuard;

let guard = AccessibilityGuard::new("accessibility")
    .with_target_grade(12.0)        // College level target
    .with_max_jargon_density(0.10)  // More lenient jargon threshold
    .with_threshold(500);           // Structure required at 500+ words

from oxideshield import AccessibilityGuard

guard = AccessibilityGuard("accessibility")
result = guard.check(response_text)

Configuration

YAML Configuration

guards:
  output:
    - guard_type: "accessibility"
      action: "suggest"
      options:
        target_grade_level: 8.0
        max_jargon_density: 0.05
        structure_threshold_words: 300
        max_avg_sentence_length: 20.0
        jargon_domains:
          - medical
          - legal
          - technical
          - financial

Proxy Gateway Aliases

The guard can be referenced by any of these names:

  • accessibility
  • accessibility_guard
  • readability

Scoring

AccessibilityGuard computes an accessibility score (0.0-1.0):

Score Meaning
1.0 Fully accessible — no issues
0.7-0.9 Minor issues — some jargon or slightly high grade level
0.4-0.7 Moderate issues — needs simplification
0.0-0.4 Significant issues — highly inaccessible

Penalties:

  • High reading level: Up to -0.4 based on grade excess
  • Jargon density: Up to -0.3 based on density excess
  • Missing structure: -0.15
  • Long sentences: Up to -0.15 based on length excess

GuardAction::Suggest

AccessibilityGuard uses the Suggest action — it does not block responses, but provides recommendations and jargon-to-plain alternatives. The passed field remains true even when issues are detected.

Best Practices

1. Apply to Output (Not Input)

AccessibilityGuard analyzes AI-generated responses. Place it in the output guard pipeline:

guards:
  output:
    - guard_type: "accessibility"
      action: "suggest"

2. Adjust Grade Level for Audience

  • General public: Grade 8 (default)
  • Healthcare consumers: Grade 6 (AHRQ recommendation)
  • Technical documentation: Grade 12
  • Academic papers: Grade 16

3. Use Alternatives for Auto-Simplification

The alternatives field maps jargon to plain language, enabling automatic text simplification:

for (jargon, plain) in &result.alternatives {
    response = response.replace(jargon, &format!("{} ({})", jargon, plain));
}

4. Combine with HelpfulnessGuard

Accessible + helpful responses provide the best user experience:

guards:
  output:
    - guard_type: "helpfulness"     # Don't over-refuse
    - guard_type: "accessibility"   # Keep it readable

References

Research Sources

  • Collective Constitutional AI (Anthropic, 2023)
  • https://www.anthropic.com/research/collective-constitutional-ai-aligning-a-language-model-with-the-collective-input-of-13k-people
  • 1,000 participants, 38,252 votes — public prioritized accessibility
  • Flesch-Kincaid (Kincaid et al., 1975)
  • Standard readability formula used by US military and education systems
  • WCAG 2.2 Guideline 3.1 — "Readable"
  • https://www.w3.org/TR/WCAG22/#readable
  • Lower secondary education level recommended
  • Plain Language Act (2010, US)
  • Federal requirement for clear government communication
  • AHRQ Health Literacy
  • 6th-grade reading level for health information
  • CDC Clear Communication Index
  • Scoring rubric for public health materials