pdf-accessibility/README's/IMPLEMENTATION_ROADMAP.md

Practical Implementation: Step-by-Step Integration

This guide provides working code examples for incrementally adding API integrations to enhance WCAG coverage.

🎯 Current State vs Target State

Basic Tool (20% WCAG):  ████░░░░░░░░░░░░░░░░░░░░░░░░
+ Free Tools (60%):     ████████████░░░░░░░░░░░░░░░░
+ Budget APIs (80%):    ████████████████░░░░░░░░░░░░
+ Full Integration (95%): ███████████████████░░░░░░░

---

Phase 1: Free Tools Integration (0 cost, +40% coverage)

Step 1.1: Add OCR Support (Tesseract)

# requirements.txt
pytesseract==0.3.10
pdf2image==1.16.3
pillow==10.0.0

# Install system dependencies:
# Ubuntu: sudo apt-get install tesseract-ocr poppler-utils
# macOS: brew install tesseract poppler

# ocr_checker.py
import pytesseract
from pdf2image import convert_from_path
from typing import List, Dict

class OCRChecker:
    def __init__(self, pdf_path: str):
        self.pdf_path = pdf_path
    
    def check_pages_for_text(self) -> List[Dict]:
        """Check each page for text using OCR"""
        results = []
        
        try:
            # Convert PDF to images
            images = convert_from_path(self.pdf_path, dpi=300)
            
            for i, image in enumerate(images):
                # Extract text
                text = pytesseract.image_to_string(image)
                
                # Get confidence data
                data = pytesseract.image_to_data(image, output_type=pytesseract.Output.DICT)
                confidences = [int(conf) for conf in data['conf'] if conf != '-1']
                avg_confidence = sum(confidences) / len(confidences) if confidences else 0
                
                results.append({
                    'page': i + 1,
                    'text_length': len(text),
                    'avg_confidence': avg_confidence,
                    'has_selectable_text': len(text.strip()) > 10,
                    'low_confidence': avg_confidence < 60
                })
        
        except Exception as e:
            print(f"OCR Error: {e}")
        
        return results
    
    def generate_ocr_report(self, results: List[Dict]) -> Dict:
        """Analyze OCR results for accessibility issues"""
        issues = []
        
        total_pages = len(results)
        pages_without_text = sum(1 for r in results if not r['has_selectable_text'])
        pages_low_confidence = sum(1 for r in results if r['low_confidence'])
        
        if pages_without_text > 0:
            issues.append({
                'severity': 'CRITICAL' if pages_without_text == total_pages else 'ERROR',
                'category': 'Text Accessibility',
                'description': f'{pages_without_text}/{total_pages} pages have no selectable text',
                'wcag': '1.1.1',
                'recommendation': 'Add OCR layer or provide accessible alternative'
            })
        
        if pages_low_confidence > 0:
            issues.append({
                'severity': 'WARNING',
                'category': 'OCR Quality',
                'description': f'{pages_low_confidence} pages have low OCR confidence (<60%)',
                'wcag': '1.1.1',
                'recommendation': 'Manual review recommended for accuracy'
            })
        
        return {
            'total_pages': total_pages,
            'pages_with_text': total_pages - pages_without_text,
            'pages_without_text': pages_without_text,
            'pages_low_confidence': pages_low_confidence,
            'issues': issues
        }

# Usage in main checker:
def integrate_ocr_check(self):
    """Add to your main checker class"""
    if self.config.enable_ocr:
        ocr_checker = OCRChecker(str(self.pdf_path))
        ocr_results = ocr_checker.check_pages_for_text()
        ocr_report = ocr_checker.generate_ocr_report(ocr_results)
        
        # Add issues to main issue list
        for issue in ocr_report['issues']:
            self.add_issue(
                Severity[issue['severity']],
                issue['category'],
                issue['description'],
                wcag_criterion=issue['wcag'],
                recommendation=issue['recommendation']
            )

Test it:

python -c "
from ocr_checker import OCRChecker
checker = OCRChecker('sample.pdf')
results = checker.check_pages_for_text()
print(checker.generate_ocr_report(results))
"

---

Step 1.2: Add Readability Analysis (TextBlob)

# requirements.txt addition
textblob==0.17.1

# First time setup:
# python -m textblob.download_corpora

# readability_checker.py
from textblob import TextBlob
import re

class ReadabilityChecker:
    def __init__(self):
        self.target_grade_level = 8  # WCAG AAA recommendation
    
    def count_syllables(self, word: str) -> int:
        """Count syllables in a word"""
        word = word.lower()
        vowels = 'aeiouy'
        syllable_count = 0
        previous_was_vowel = False
        
        for char in word:
            is_vowel = char in vowels
            if is_vowel and not previous_was_vowel:
                syllable_count += 1
            previous_was_vowel = is_vowel
        
        # Adjust for silent 'e'
        if word.endswith('e') and syllable_count > 1:
            syllable_count -= 1
        
        return max(1, syllable_count)
    
    def analyze_text(self, text: str) -> Dict:
        """Comprehensive readability analysis"""
        
        # Clean text
        text = re.sub(r'\s+', ' ', text.strip())
        
        if not text:
            return {'error': 'No text to analyze'}
        
        # Create TextBlob
        blob = TextBlob(text)
        sentences = blob.sentences
        words = blob.words
        
        # Calculate metrics
        total_words = len(words)
        total_sentences = len(sentences)
        total_syllables = sum(self.count_syllables(word) for word in words)
        
        if total_sentences == 0 or total_words == 0:
            return {'error': 'Insufficient text'}
        
        # Flesch Reading Ease (0-100, higher is easier)
        flesch_reading_ease = (
            206.835 
            - 1.015 * (total_words / total_sentences)
            - 84.6 * (total_syllables / total_words)
        )
        
        # Flesch-Kincaid Grade Level
        fk_grade_level = (
            0.39 * (total_words / total_sentences)
            + 11.8 * (total_syllables / total_words)
            - 15.59
        )
        
        # Average sentence length
        avg_sentence_length = total_words / total_sentences
        
        # Find long sentences (>25 words)
        long_sentences = [
            str(sent) for sent in sentences 
            if len(sent.words) > 25
        ]
        
        # Find complex words (>3 syllables)
        complex_words = [
            word for word in words 
            if self.count_syllables(word) > 3
        ]
        
        return {
            'flesch_reading_ease': round(flesch_reading_ease, 2),
            'flesch_kincaid_grade': round(fk_grade_level, 2),
            'avg_sentence_length': round(avg_sentence_length, 2),
            'total_words': total_words,
            'total_sentences': total_sentences,
            'long_sentences_count': len(long_sentences),
            'long_sentences': long_sentences[:5],  # First 5
            'complex_words_count': len(complex_words),
            'complex_words': list(set(complex_words))[:10]  # First 10 unique
        }
    
    def generate_readability_issues(self, analysis: Dict) -> List[Dict]:
        """Generate accessibility issues based on readability"""
        issues = []
        
        if 'error' in analysis:
            return issues
        
        # Flesch Reading Ease interpretation
        # 90-100: Very Easy (5th grade)
        # 60-70: Standard (8th-9th grade)
        # 30-50: Difficult (College)
        # 0-30: Very Difficult (College graduate)
        
        if analysis['flesch_reading_ease'] < 60:
            issues.append({
                'severity': 'WARNING',
                'category': 'Readability',
                'description': f"Content readability score: {analysis['flesch_reading_ease']}/100 (target: 60+)",
                'wcag': '3.1.5',
                'recommendation': 'Simplify language to reach 8th-9th grade level'
            })
        
        if analysis['flesch_kincaid_grade'] > self.target_grade_level:
            issues.append({
                'severity': 'INFO',
                'category': 'Reading Level',
                'description': f"Content requires grade {analysis['flesch_kincaid_grade']} reading level (target: {self.target_grade_level})",
                'wcag': '3.1.5',
                'recommendation': 'Consider simplifying vocabulary and sentence structure'
            })
        
        if analysis['avg_sentence_length'] > 25:
            issues.append({
                'severity': 'WARNING',
                'category': 'Sentence Complexity',
                'description': f"Average sentence length: {analysis['avg_sentence_length']} words (target: <25)",
                'wcag': '3.1.5',
                'recommendation': 'Break long sentences into shorter ones'
            })
        
        if analysis['long_sentences_count'] > 5:
            issues.append({
                'severity': 'INFO',
                'category': 'Long Sentences',
                'description': f"{analysis['long_sentences_count']} sentences exceed 25 words",
                'wcag': '3.1.5',
                'recommendation': 'Review and simplify long sentences'
            })
        
        return issues

# Integration example:
def integrate_readability_check(self):
    """Add to your main checker class"""
    if self.config.enable_content_analysis:
        # Extract all text from PDF
        all_text = ""
        for page in self.pdf_plumber.pages:
            text = page.extract_text()
            if text:
                all_text += text + "\n"
        
        if len(all_text) > 100:  # Only analyze if sufficient text
            checker = ReadabilityChecker()
            analysis = checker.analyze_text(all_text)
            issues = checker.generate_readability_issues(analysis)
            
            # Add to main issues
            for issue in issues:
                self.add_issue(
                    Severity[issue['severity']],
                    issue['category'],
                    issue['description'],
                    wcag_criterion=issue['wcag'],
                    recommendation=issue['recommendation']
                )

Test it:

python -c "
from readability_checker import ReadabilityChecker
checker = ReadabilityChecker()
text = 'Your PDF text here. Multiple sentences help. Add more content for better analysis.'
analysis = checker.analyze_text(text)
print(analysis)
print(checker.generate_readability_issues(analysis))
"

---

Step 1.3: Add Color Contrast Checking

# contrast_checker.py
from PIL import Image
from pdf2image import convert_from_path
import numpy as np
from typing import List, Tuple, Dict

class ContrastChecker:
    def __init__(self):
        self.wcag_aa_normal = 4.5  # Normal text
        self.wcag_aa_large = 3.0   # Large text (18pt+)
    
    def get_luminance(self, rgb: Tuple[int, int, int]) -> float:
        """Calculate relative luminance per WCAG formula"""
        r, g, b = [x / 255.0 for x in rgb]
        
        r = r / 12.92 if r <= 0.03928 else ((r + 0.055) / 1.055) ** 2.4
        g = g / 12.92 if g <= 0.03928 else ((g + 0.055) / 1.055) ** 2.4
        b = b / 12.92 if b <= 0.03928 else ((b + 0.055) / 1.055) ** 2.4
        
        return 0.2126 * r + 0.7152 * g + 0.0722 * b
    
    def calculate_contrast_ratio(self, color1: Tuple[int, int, int], 
                                 color2: Tuple[int, int, int]) -> float:
        """Calculate WCAG contrast ratio between two colors"""
        l1 = self.get_luminance(color1)
        l2 = self.get_luminance(color2)
        
        lighter = max(l1, l2)
        darker = min(l1, l2)
        
        return (lighter + 0.05) / (darker + 0.05)
    
    def check_page_contrast(self, pdf_path: str, page_num: int, 
                           sample_size: int = 200) -> Dict:
        """Sample page for potential contrast issues"""
        
        images = convert_from_path(
            pdf_path, 
            first_page=page_num, 
            last_page=page_num, 
            dpi=150
        )
        
        if not images:
            return {'error': 'Could not convert page'}
        
        image = images[0].convert('RGB')
        width, height = image.size
        
        low_contrast_samples = []
        
        # Sample random points
        for _ in range(sample_size):
            x = np.random.randint(0, width - 2)
            y = np.random.randint(0, height - 1)
            
            # Get adjacent pixels (potential text/background)
            color1 = image.getpixel((x, y))
            color2 = image.getpixel((x + 1, y))
            
            ratio = self.calculate_contrast_ratio(color1, color2)
            
            if ratio < self.wcag_aa_normal:
                low_contrast_samples.append({
                    'position': (x, y),
                    'color1': color1,
                    'color2': color2,
                    'ratio': round(ratio, 2),
                    'passes_large_text': ratio >= self.wcag_aa_large
                })
        
        # Analyze results
        total_samples = sample_size
        low_contrast_count = len(low_contrast_samples)
        critical_count = sum(1 for s in low_contrast_samples if s['ratio'] < self.wcag_aa_large)
        
        return {
            'page': page_num,
            'total_samples': total_samples,
            'low_contrast_count': low_contrast_count,
            'critical_count': critical_count,
            'percentage_low_contrast': (low_contrast_count / total_samples) * 100,
            'samples': low_contrast_samples[:10]  # First 10 for review
        }
    
    def generate_contrast_issues(self, results: Dict) -> List[Dict]:
        """Generate issues from contrast check results"""
        issues = []
        
        if 'error' in results:
            return issues
        
        # If more than 10% of samples fail
        if results['percentage_low_contrast'] > 10:
            severity = 'ERROR' if results['critical_count'] > 5 else 'WARNING'
            
            issues.append({
                'severity': severity,
                'category': 'Color Contrast',
                'description': f"Page {results['page']}: {results['percentage_low_contrast']:.1f}% of samples have insufficient contrast",
                'wcag': '1.4.3',
                'recommendation': 'Use Colour Contrast Analyser tool to verify specific areas'
            })
        
        if results['critical_count'] > 0:
            issues.append({
                'severity': 'WARNING',
                'category': 'Color Contrast',
                'description': f"Page {results['page']}: {results['critical_count']} samples fail even large text standards",
                'wcag': '1.4.3',
                'recommendation': 'Critical contrast issues detected - manual review required'
            })
        
        return issues

# Integration:
def integrate_contrast_check(self):
    """Add to your main checker"""
    if self.config.enable_contrast_check:
        checker = ContrastChecker()
        
        for i in range(len(self.pdf_reader.pages)):
            results = checker.check_page_contrast(str(self.pdf_path), i + 1)
            issues = checker.generate_contrast_issues(results)
            
            for issue in issues:
                self.add_issue(
                    Severity[issue['severity']],
                    issue['category'],
                    issue['description'],
                    page_number=i + 1,
                    wcag_criterion=issue['wcag'],
                    recommendation=issue['recommendation']
                )

---

Phase 2: Budget API Integration (~$10/month, +20% coverage)

Step 2.1: OpenAI Image Analysis (On-Demand)

# ai_image_checker.py
import openai
import base64
from typing import Dict, List

class AIImageChecker:
    def __init__(self, api_key: str):
        self.client = openai.OpenAI(api_key=api_key)
    
    def analyze_image(self, image_bytes: bytes, 
                     existing_alt_text: str = None) -> Dict:
        """Analyze image with GPT-4 Vision"""
        
        # Encode image
        base64_image = base64.b64encode(image_bytes).decode('utf-8')
        
        if existing_alt_text:
            prompt = f"""You are an accessibility expert. Evaluate this alt text:

Alt text: "{existing_alt_text}"

Provide:
1. Quality score (1-10)
2. What's missing
3. What's good
4. Improved version

Be concise. Format as JSON."""
        else:
            prompt = """Provide a concise alt text (1-2 sentences) for accessibility.
Focus on information conveyed, not artistic details.
Also indicate if this image contains text (WCAG 1.4.5 issue).

Format as JSON: {"alt_text": "...", "has_text": true/false, "text_content": "..."}"""
        
        try:
            response = self.client.chat.completions.create(
                model="gpt-4-vision-preview",
                messages=[
                    {
                        "role": "user",
                        "content": [
                            {"type": "text", "text": prompt},
                            {
                                "type": "image_url",
                                "image_url": {
                                    "url": f"data:image/jpeg;base64,{base64_image}",
                                    "detail": "low"  # Use 'low' to save costs
                                }
                            }
                        ]
                    }
                ],
                max_tokens=200
            )
            
            return {
                'success': True,
                'analysis': response.choices[0].message.content,
                'cost_estimate': 0.01  # Approximate
            }
        
        except Exception as e:
            return {
                'success': False,
                'error': str(e)
            }
    
    def batch_analyze_critical_images(self, images: List[bytes], 
                                     max_images: int = 10) -> List[Dict]:
        """Analyze only the most critical images to control costs"""
        
        results = []
        
        # Analyze up to max_images
        for i, img_bytes in enumerate(images[:max_images]):
            print(f"Analyzing image {i+1}/{min(len(images), max_images)}...")
            result = self.analyze_image(img_bytes)
            results.append(result)
        
        if len(images) > max_images:
            print(f"Note: {len(images) - max_images} images not analyzed to control costs")
        
        return results

# Usage with cost control:
def integrate_ai_images(self, max_images_per_doc: int = 10):
    """Smart integration with cost control"""
    
    if not self.config.vision_api_key:
        return
    
    checker = AIImageChecker(self.config.vision_api_key)
    
    # Collect all images
    all_images = []
    for page_num, page in enumerate(self.pdf_plumber.pages):
        for img in page.images:
            all_images.append({
                'page': page_num + 1,
                'image': img,
                'bytes': self._extract_image_bytes(img)
            })
    
    # Only analyze first N images
    if len(all_images) > max_images_per_doc:
        self.add_issue(
            Severity.INFO,
            "AI Image Analysis",
            f"Document has {len(all_images)} images. Analyzing first {max_images_per_doc} to control costs.",
            recommendation=f"Remaining {len(all_images) - max_images_per_doc} images need manual review"
        )
    
    # Analyze images
    results = checker.batch_analyze_critical_images(
        [img['bytes'] for img in all_images],
        max_images=max_images_per_doc
    )
    
    # Process results
    for img_data, analysis in zip(all_images[:max_images_per_doc], results):
        if analysis['success']:
            # Parse analysis and create issues
            self.add_issue(
                Severity.WARNING,
                "Image Alt Text",
                f"Page {img_data['page']}: AI suggests alt text improvement",
                page_number=img_data['page'],
                wcag_criterion="1.1.1",
                recommendation=analysis['analysis'][:200]
            )

---

Step 2.2: Usage Example with All Free Tools

# complete_free_integration.py

from enhanced_pdf_checker import EnhancedPDFAccessibilityChecker, EnhancedCheckConfig
from ocr_checker import OCRChecker
from readability_checker import ReadabilityChecker
from contrast_checker import ContrastChecker

def run_complete_free_analysis(pdf_path: str):
    """Run all free checks for maximum coverage"""
    
    # Configure
    config = EnhancedCheckConfig(
        enable_ocr=True,
        enable_contrast_check=True,
        enable_content_analysis=True,
        enable_link_validation=True,
        verbose=True
    )
    
    # Run main checker
    checker = EnhancedPDFAccessibilityChecker(pdf_path, config)
    issues = checker.check_all()
    
    # Generate report
    report = checker.generate_report('html')
    
    # Save report
    output_path = pdf_path.replace('.pdf', '_accessibility_report.html')
    with open(output_path, 'w') as f:
        f.write(report)
    
    print(f"\n✅ Analysis complete!")
    print(f"📊 Found {len(issues)} issues")
    print(f"📄 Report saved: {output_path}")
    
    return issues

# Run it:
if __name__ == "__main__":
    import sys
    
    if len(sys.argv) < 2:
        print("Usage: python complete_free_integration.py <pdf_file>")
        sys.exit(1)
    
    pdf_file = sys.argv[1]
    issues = run_complete_free_analysis(pdf_file)
    
    # Print summary
    severity_counts = {}
    for issue in issues:
        sev = issue.severity.value
        severity_counts[sev] = severity_counts.get(sev, 0) + 1
    
    print("\nSummary:")
    for severity, count in sorted(severity_counts.items()):
        print(f"  {severity}: {count}")

---

🎯 Quick Start Commands

Install everything (Free tools):

# System dependencies
sudo apt-get install tesseract-ocr poppler-utils  # Ubuntu
brew install tesseract poppler  # macOS

# Python packages
pip install pypdf pdfplumber pillow pdf2image pytesseract textblob numpy --break-system-packages

# Download TextBlob corpora
python -m textblob.download_corpora

Run complete free analysis:

python complete_free_integration.py your_document.pdf

Add OpenAI for image analysis:

pip install openai --break-system-packages
export OPENAI_API_KEY="sk-your-key-here"
python complete_free_integration.py your_document.pdf --enable-ai-images

---

📊 Coverage Progress Tracker

After implementing each phase, you'll achieve:

Phase	Tools Added	WCAG Coverage	Monthly Cost
Baseline	Basic PDF checks	20%	$0
Phase 1.1	+ OCR (Tesseract)	35%	$0
Phase 1.2	+ Readability	50%	$0
Phase 1.3	+ Contrast	60%	$0
Phase 2.1	+ AI Images (limited)	80%	~$10
Phase 2.2	+ AI Images (full)	90%	~$50
Phase 3	+ Document AI	95%	~$100

---

🧪 Testing Your Integration

Create this test script:

# test_integration.sh
#!/bin/bash

echo "Testing PDF Accessibility Checker Integration"
echo "=============================================="

# Test 1: Basic checks
echo "Test 1: Basic checks (no APIs)..."
python enhanced_pdf_checker.py sample.pdf --format text

# Test 2: With OCR
echo "Test 2: With OCR..."
python enhanced_pdf_checker.py sample.pdf --enable-ocr

# Test 3: With contrast checking
echo "Test 3: With contrast..."
python enhanced_pdf_checker.py sample.pdf --check-contrast

# Test 4: Full free analysis
echo "Test 4: Complete free analysis..."
python complete_free_integration.py sample.pdf

echo "✅ All tests complete!"

---

Next Steps

1. Start with Phase 1 (Free tools) - Get to 60% coverage
2. Measure impact - Track issues found vs manual review
3. Add Phase 2 selectively - Use AI only for critical documents
4. Optimize costs - Cache results, batch process, use low-detail images
5. Build pipeline - Integrate into CI/CD for automated checking

The code is ready to use - just install dependencies and run!