Intelligent Accessibility Assistant (IAA)

An AI-enhanced, open-source Python framework for automated accessibility testing that combines rule-based WCAG validation with intelligent explanations and code remediation.

🎯 Features

• Automated WCAG Testing: Rule-based accessibility checks using axe-core integration
• AI-Enhanced Explanations: Plain-language explanations of accessibility issues
• Code Remediation: Automated fix suggestions for common violations
• Multiple Platforms: Web (Playwright), Mobile (Appium - coming soon)
• Flexible Reporting: JSON, HTML, and Markdown output formats
• CI/CD Ready: Exit codes and thresholds for pipeline integration
• Privacy-First: Offline AI mode with rule-based explanations
• Extensible: Plugin architecture for custom modules

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/yourusername/intelligent-accessibility-assistant.git
cd intelligent-accessibility-assistant

# Install dependencies
pip install -e .

# Install Playwright browsers
playwright install chromium

Basic Usage

# Test a website
iaa test https://example.com

# Generate JSON report
iaa test https://example.com --format json --output report.json

# Disable AI enhancements
iaa test https://example.com --no-ai

# Run in CI mode with failure threshold
iaa test https://example.com --fail-on critical --fail-threshold 0

📋 Requirements

• Python 3.9+
• Playwright (for web testing)
• Optional: OpenAI/Anthropic API key (for online AI mode)

🏗️ Architecture

Core Components

iaa/
├── core/
│   ├── models.py          # Data models (AccessibilityIssue, TestResult)
│   ├── module.py          # Base module interface
│   └── engine.py          # Orchestration engine
├── modules/
│   ├── web.py             # Web accessibility module (Playwright + axe-core)
│   └── ai/
│       ├── explainer.py   # AI-powered issue explanations
│       ├── fixer.py       # Code remediation generator
│       └── enhancer.py    # AI enhancement wrapper
├── reporters/
│   ├── json_reporter.py   # JSON output
│   └── html_reporter.py   # HTML report generation
└── cli.py                 # Command-line interface

How It Works

1. Module Execution: The engine orchestrates one or more accessibility modules (web, mobile, etc.)
2. Rule-Based Testing: Each module runs automated checks (e.g., axe-core for web)
3. Issue Collection: Violations are collected as AccessibilityIssue objects
4. AI Enhancement (optional): Issues are enhanced with:
   • Plain-language explanations
   • Impact descriptions
   • Suggested code fixes
5. Reporting: Results are formatted and output in the requested format
6. CI Integration: Exit codes indicate pass/fail based on thresholds

Plugin Architecture

Create custom modules by extending AccessibilityModule:

from iaa.core.module import AccessibilityModule
from iaa.core.models import AccessibilityIssue

class CustomModule(AccessibilityModule):
    @property
    def name(self) -> str:
        return "custom_module"
    
    async def run(self, target: str) -> List[AccessibilityIssue]:
        # Your testing logic here
        return []

🔧 Configuration

CLI Options

Option	Description	Default
--format	Output format (json, html, markdown)	html
--output	Output file path	accessibility-report.html
--ai-enabled	Enable AI enhancements	True
--offline-ai	Use offline AI mode	True
--fail-on	Fail on severity level	critical
--fail-threshold	Maximum issues before failure	0
--headless	Run browser in headless mode	True

AI Modes

Offline Mode (default):

• Uses rule-based explanations and template fixes
• No external API calls
• Privacy-preserving
• No API key required

Online Mode (coming soon):

• Integrates with OpenAI, Anthropic, or local LLMs
• Context-aware explanations
• Intelligent code remediation
• Requires API key

📊 Report Formats

HTML Report

Beautiful, interactive HTML report with:

• Summary dashboard
• Severity-coded issues
• AI explanations and fixes
• WCAG references

JSON Report

Structured data for programmatic processing:

{
  "target": "https://example.com",
  "summary": {
    "total_issues": 5,
    "critical": 2,
    "serious": 1
  },
  "issues": [...]
}

🔐 Privacy & Security

• Data Masking: Sensitive data is masked before AI processing
• Offline Mode: Default mode requires no external API calls
• No PII: Framework avoids collecting personally identifiable information
• Audit Logging: AI usage is logged for compliance

🧪 Testing

# Run tests
pytest

# Run with coverage
pytest --cov=iaa

🛣️ Roadmap

• Web accessibility module (Playwright + axe-core)
• AI explanation engine
• AI fix generator
• HTML/JSON reporting
• Mobile accessibility module (Appium)
• Screen reader simulation
• Vision-based UI analysis
• Online AI integration (OpenAI, Anthropic)
• Markdown reporter
• VPAT generation
• Git repository scanning

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• axe-core for accessibility rules
• Playwright for browser automation
• Typer for CLI framework

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for a more accessible web