prompt508 0.2.0

Accessibility & Plain-Language Optimizer for AI Prompts - Section 508 Compliance with Two-Stage AI Pipeline

prompt508

Accessibility & Plain-Language Optimizer for AI Prompts

🎯 Section 508 Compliance for AI Systems

prompt508 is an open-source Python library that analyzes and optimizes AI prompts to ensure they meet U.S. Section 508 accessibility and plain-language compliance standards. It helps developers, government agencies, and enterprises create AI systems that produce readable, inclusive, and compliant responses by design.

📋 Table of Contents

• Features
• Installation
• Quick Start
• Usage
  • Python API
  • Command Line
• Core Capabilities
• Examples
• Configuration
• Development
• Contributing
• License

✨ Features

Core Analysis & Optimization

• 📊 Readability Analysis - Computes Flesch-Kincaid grade level and multiple readability metrics
• 📝 Jargon Detection - Identifies technical terms, undefined acronyms, and complex language
• 🎭 Tone Analysis - Analyzes sentiment, formality, and passive voice usage
• ♿ Accessibility Hints - Injects Section 508 compliance reminders (alt text, captions, structure)
• 🔧 Rule-Based Optimization - Automatically rewrites prompts using plain language guidelines

🆕 Two-Stage AI Pipeline (NEW!)

• Stage 1: INPUT Enhancement - Automatically adds Section 508 instructions to prompts (free)
• Stage 2: OUTPUT Validation & Fixing - Checks and rewrites LLM outputs for compliance
• 🤖 AI-Powered Rewriting - Uses OpenAI to intelligently improve accessibility
• 💰 Cost-Efficient - Only ~$0.0001-0.0004 per request
• 📈 Proven Results - +24 point score improvements, 5.6 grade level reduction

Additional Features

• 🖥️ CLI Interface - Easy command-line tools for analysis, optimization, and rewriting
• 🔒 Offline-First - Works without external APIs by default (FedRAMP/Zero Trust ready)
• 🔄 Smart Fallback - Gracefully falls back to rule-based mode when no API key available

📦 Installation

Basic Installation

pip install prompt508

Install with LLM Support (Optional)

pip install prompt508[llm]

Install for Development

pip install prompt508[dev]

Post-Installation: spaCy Model

After installation, download the required spaCy language model:

python -m spacy download en_core_web_sm

🚀 Quick Start

Python API

from prompt508 import AccessibilityAdvisor

# Initialize the advisor
advisor = AccessibilityAdvisor(target_grade=8.0, include_alt_text=True)

# Analyze a prompt
prompt = "Utilize the API to facilitate data transmission and implement visualization."
analysis = advisor.analyze(prompt)

print(f"Overall Score: {analysis['overall_score']}/100")
print(f"Grade Level: {analysis['readability']['flesch_kincaid_grade']}")
print(f"Issues: {len(analysis['issues'])}")

# Optimize the prompt
optimized = advisor.optimize(prompt)
print(f"Optimized: {optimized}")

Command Line

# Analyze a prompt
prompt508 analyze "Your prompt text here"

# Optimize a prompt
prompt508 optimize "Utilize the API to facilitate transmission" --type images

# Generate a detailed report
prompt508 report --file prompt.txt --output report.txt

📖 Usage

Python API

Basic Analysis

from prompt508 import AccessibilityAdvisor

advisor = AccessibilityAdvisor(target_grade=8.0)

prompt = "Generate a comprehensive visualization of seismic telemetry data."
analysis = advisor.analyze(prompt)

# Access detailed results
print(f"Readability Grade: {analysis['readability']['flesch_kincaid_grade']}")
print(f"Jargon Count: {analysis['jargon']['jargon_count']}")
print(f"Tone: {analysis['tone']['tone_classification']}")
print(f"Passes Compliance: {analysis['passes_compliance']}")

Prompt Optimization

# Basic optimization
optimized = advisor.optimize(prompt)

# Optimization with content type hints
optimized = advisor.optimize(
    prompt,
    content_type="images",  # Adds image-specific accessibility hints
    apply_rule_based_fixes=True
)

# Generate comprehensive report
report = advisor.get_report(prompt)
print(report)

Individual Analyzers

from prompt508 import ReadabilityAnalyzer, JargonDetector, ToneAnalyzer

# Readability only
readability = ReadabilityAnalyzer(target_grade=8.0)
scores = readability.score_text("Your text here")

# Jargon detection only
jargon = JargonDetector()
issues = jargon.detect_jargon("Your text here")

# Tone analysis only
tone = ToneAnalyzer(target_tone="neutral")
sentiment = tone.analyze_tone("Your text here")

Command Line

Analyze Command

# Analyze text directly
prompt508 analyze "Your prompt text"

# Analyze from file
prompt508 analyze --file prompt.txt

# Set custom grade level target
prompt508 analyze "Your text" --grade 6

# Use strict mode
prompt508 analyze "Your text" --strict

# Output as JSON
prompt508 analyze "Your text" --json

Optimize Command

# Optimize text
prompt508 optimize "Utilize the API to facilitate transmission"

# Optimize with file input/output
prompt508 optimize --file input.txt --output optimized.txt

# Specify content type for targeted hints
prompt508 optimize "Generate chart" --type images

# Skip rule-based replacements
prompt508 optimize "Your text" --no-fixes

# Strict mode with grade 6 target
prompt508 optimize "Your text" --grade 6 --strict

Report Command

# Generate detailed report
prompt508 report "Your prompt text"

# Save report to file
prompt508 report --file prompt.txt --output report.txt

Rewrite Command (NEW!)

# AI-powered rewriting (requires OPENAI_API_KEY in environment or .env)
prompt508 rewrite "Utilize sophisticated methodology to facilitate implementation"

# Rewrite from file
prompt508 rewrite --file input.txt --output rewritten.txt

# Use specific OpenAI model
prompt508 rewrite "Complex text" --model gpt-4o

# Provide API key directly
prompt508 rewrite "Text" --api-key sk-proj-...

# Skip analysis comparison
prompt508 rewrite "Text" --no-analysis

# Setup .env file for API key
echo "OPENAI_API_KEY=sk-proj-your-key-here" > .env

🔍 Core Capabilities

1. Readability Analysis

Computes multiple readability metrics:

• Flesch-Kincaid Grade Level - Target: 8th grade or below
• Flesch Reading Ease - Score: 60-100 (easier to read)
• Gunning Fog Index - Estimates years of education needed
• SMOG Index - Alternative readability formula
• Word & Sentence Statistics - Length and complexity metrics

2. Jargon Detection

Identifies problematic terminology:

• Technical jargon with plain language alternatives
• Undefined acronyms requiring expansion
• Complex words (3+ syllables)
• Government jargon per PlainLanguage.gov guidelines

3. Tone & Sentiment Analysis

Assesses communication style:

• Sentiment polarity - Negative, neutral, or positive
• Subjectivity - Objective vs. subjective language
• Formality level - Formal, neutral, or informal
• Passive voice detection - Encourages active voice

4. Accessibility Injection

Adds Section 508 compliance hints:

• Alt text reminders for images
• Caption requirements for multimedia
• Document structure guidelines (headings, lists)
• Link text best practices
• Plain language reminders

5. Rule-Based Optimization

Automatically improves prompts:

• Replaces jargon with plain language
• Expands common acronyms
• Simplifies complex phrases
• Injects accessibility instructions

💡 Examples

Example 1: Government Documentation

from prompt508 import AccessibilityAdvisor

advisor = AccessibilityAdvisor(target_grade=8.0, strict_mode=True)

# Original problematic prompt
original = """
Pursuant to Section 508 requirements, utilize the API to facilitate 
transmission of telemetry data. Subsequently, implement visualization 
methodologies to demonstrate magnitude distributions.
"""

# Analyze
analysis = advisor.analyze(original)
print(f"Issues: {analysis['issues']}")
# Output: ['Reading level too high: Grade 15.2 (target: 8.0)', 
#          'Found 4 jargon terms', ...]

# Optimize
optimized = advisor.optimize(original, content_type="images")
print(optimized)
# Output: "Following Section 508 requirements, use the API to send 
#          earthquake data. Then, create charts to show the size patterns.
#
#          [Accessibility Requirements]
#          - Include descriptive alt text for all images
#          - Describe the content and function of images..."

Example 2: Enterprise AI System

# Check if AI prompts meet compliance before deployment
prompts_to_check = [
    "Generate a summary of the quarterly financial report",
    "Create visualization showing customer satisfaction metrics",
    "Analyze sentiment in customer feedback data"
]

advisor = AccessibilityAdvisor(target_grade=8.0)

for prompt in prompts_to_check:
    analysis = advisor.analyze(prompt)
    if not analysis['passes_compliance']:
        print(f"❌ Prompt needs improvement: {prompt}")
        print(f"   Issues: {analysis['issues']}")
        optimized = advisor.optimize(prompt)
        print(f"   Suggested: {optimized}\n")
    else:
        print(f"✅ Prompt passes compliance: {prompt}\n")

Example 3: Two-Stage AI Pipeline (NEW!)

from prompt508 import AccessibilityAdvisor
from openai import OpenAI

# Your LLM function
def my_llm(prompt):
    client = OpenAI()  # Uses OPENAI_API_KEY from environment
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

advisor = AccessibilityAdvisor()

# Complete two-stage pipeline
result = advisor.ensure_compliance(
    prompt="Explain how APIs work",
    llm_function=my_llm
)

print(f"Stages used: {result['stages_used']}")
# Output: {'stage1_enhance': True, 'stage2_fix': True}

print(f"Was fixed: {result['was_fixed']}")
# Output: True (if Stage 2 fixing was needed)

print(f"Final score: {result['compliance_score']}/100")
# Output: 85.3/100

print(f"Final output: {result['final_output']}")
# Output: Clean, accessible text meeting Section 508 standards

Manual stage-by-stage control:

# Stage 1: Enhance prompt with Section 508 instructions
enhanced_prompt = advisor.enhance_prompt_for_508("Explain quantum computing")

# Send to your LLM
llm_output = my_llm(enhanced_prompt)

# Stage 2: Validate the output
validation = advisor.validate_output(llm_output)
print(f"Score: {validation['score']}/100")
print(f"Needs fixing: {validation['needs_fixing']}")

# Stage 2: Fix if needed
if validation['needs_fixing']:
    fixed = advisor.fix_output(llm_output)
    final_text = fixed['rewritten']
    print(f"Cost: ${fixed['cost_usd']:.4f}")
else:
    final_text = llm_output

print(f"Final: {final_text}")

Example 4: AI-Powered Rewriting

# Rewrite any text for accessibility (requires OpenAI API key)
advisor = AccessibilityAdvisor()

complex_text = "Utilize sophisticated methodology to facilitate implementation"

result = advisor.rewrite_prompt(complex_text)

if result['mode'] == 'ai':
    print(f"Rewritten: {result['rewritten']}")
    # Output: "Use this simple method to help with implementation"
    
    print(f"Improvements:")
    print(f"  Score: {result['improvements']['overall_score']['before']} → "
          f"{result['improvements']['overall_score']['after']}")
    print(f"  Grade: {result['improvements']['readability_grade']['before']} → "
          f"{result['improvements']['readability_grade']['after']}")
    print(f"  Cost: ${result['cost_usd']:.4f}")

Example 5: Individual Module Usage

from prompt508 import score_text, detect_jargon, analyze_tone

text = "Implement comprehensive accessibility features"

# Quick readability check
readability = score_text(text)
print(f"Grade Level: {readability['flesch_kincaid_grade']}")

# Quick jargon check
jargon = detect_jargon(text)
print(f"Jargon terms: {jargon['jargon_words']}")
print(f"Suggestions: {jargon['suggestions']}")

# Quick tone check
tone = analyze_tone(text)
print(f"Sentiment: {tone['tone_classification']}")
print(f"Formality: {tone['formality_score']}")

Example 6: Comparison Demo

See the VALUE_PROPOSITION.md file for a complete comparison showing:

• WITHOUT prompt508: Score 56.7/100, Grade 13.8, 17 jargon terms
• WITH prompt508: Score 80.7/100, Grade 8.2, 6 jargon terms
• Improvement: +24 points, -5.6 grades, -11 jargon terms
• Cost: Only $0.0004 per request

Run the demo:

python demo_comparison.py

⚙️ Configuration

AccessibilityAdvisor Parameters

advisor = AccessibilityAdvisor(
    target_grade=8.0,              # Target reading grade level (default: 8.0)
    include_alt_text=True,         # Include alt text reminders
    include_captions=True,          # Include caption reminders
    include_structure=True,         # Include structure reminders
    strict_mode=False,             # Use stricter analysis
    spacy_model="en_core_web_sm"   # spaCy model for NLP
)

Content Types

When optimizing, specify content type for targeted hints:

• "images" - Image alt text and descriptions
• "multimedia" - Video captions and transcripts
• "documents" - Document structure and headings
• "links" - Link text best practices
• "forms" - Form accessibility
• None - General accessibility hints

🛠️ Development

Setup Development Environment

# Clone the repository
git clone https://github.com/hungmanhdo/prompt508.git
cd prompt508

# Install in development mode with all dependencies
pip install -e ".[dev]"

# Download spaCy model
python -m spacy download en_core_web_sm

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=prompt508 --cov-report=html

# Run specific test file
pytest tests/test_readability.py -v

Code Quality

# Format code with black
black src/

# Check code style with flake8
flake8 src/

# Type checking with mypy
mypy src/

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• PlainLanguage.gov - Federal plain language guidelines
• Section 508 - U.S. accessibility standards (29 U.S.C. § 794d)
• WCAG 2.1 - Web Content Accessibility Guidelines
• textstat - Readability calculations
• spaCy - Natural language processing
• TextBlob - Sentiment analysis

📚 Resources

• Section 508 Standards
• PlainLanguage.gov
• WCAG 2.1 Guidelines
• Federal Plain Language Guidelines

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for accessibility and inclusion