How to Build an AI Accessibility Assistant That Describes Images and Reads Documents Aloud

ai-accessibility-assistant/
├── app/
│   ├── __init__.py
│   ├── wcag_validator.py
│   └── accessible_html_builder.py
├── tests/
│   └── test_accessibility_assistant.py
└── requirements.txt

from typing import Tuple, List

def _srgb_channel_to_linear(channel_8bit: int) -> float:
    c = channel_8bit / 255.0
    return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4

def compute_relative_luminance(hex_color: str) -> float:
    """Computes W3C WCAG 2.2 relative luminance L for a 6-digit hex color (#RRGGBB)."""
    clean = hex_color.lstrip("#")
    if len(clean) != 6:
        raise ValueError(f"Expected 6-digit hex color, got: {hex_color}")
    r = _srgb_channel_to_linear(int(clean[0:2], 16))
    g = _srgb_channel_to_linear(int(clean[2:4], 16))
    b = _srgb_channel_to_linear(int(clean[4:6], 16))
    return 0.2126 * r + 0.7152 * g + 0.0722 * b

def compute_wcag_contrast_ratio(fg_hex: str, bg_hex: str) -> Tuple[float, bool, bool]:
    """Returns (contrast_ratio, passes_aa_normal_4_5, passes_aaa_normal_7_0)."""
    l1 = compute_relative_luminance(fg_hex)
    l2 = compute_relative_luminance(bg_hex)
    lighter = max(l1, l2)
    darker = min(l1, l2)
    ratio = round((lighter + 0.05) / (darker + 0.05), 2)
    return ratio, (ratio >= 4.5), (ratio >= 7.0)

def validate_heading_hierarchy(heading_levels: List[int]) -> List[str]:
    """Verifies that document headings start at H1 and never skip levels downward (e.g. H1 -> H3)."""
    errors: List[str] = []
    if not heading_levels:
        return ["Document contains no headings for screen-reader navigation."]
    if heading_levels[0] != 1:
        errors.append(f"First heading should be H1, found H{heading_levels[0]}.")
    for prev, curr in zip(heading_levels, heading_levels[1:]):
        if curr > prev + 1:
            errors.append(f"Skipped heading level from H{prev} to H{curr}.")
    return errors

import html
from typing import List, Optional
from pydantic import BaseModel, Field

class AccessibleFigureDescription(BaseModel):
    figure_id: str
    concise_alt_text: str = Field(..., max_length=125, description="Short objective alt text <= 125 chars.")
    detailed_spatial_description: str = Field(..., description="Thorough layout and visual description.")
    extracted_ocr_text: Optional[str] = None
    chart_data_rows: Optional[List[List[str]]] = Field(
        None, description="Optional tabular rows [header_row, ...data_rows] if the image is a chart."
    )

def render_accessible_figure_html(fig: AccessibleFigureDescription, image_src: str) -> str:
    """Renders WCAG 2.2 compliant <figure> with concise alt text, <details> disclosure, and accessible data table."""
    safe_alt = html.escape(fig.concise_alt_text)
    safe_detail = html.escape(fig.detailed_spatial_description)
    desc_id = f"desc-{html.escape(fig.figure_id)}"

    table_html = ""
    if fig.chart_data_rows and len(fig.chart_data_rows) >= 2:
        headers = "".join(f"<th scope='col'>{html.escape(h)}</th>" for h in fig.chart_data_rows[0])
        body_rows = []
        for row in fig.chart_data_rows[1:]:
            cells = "".join(f"<td>{html.escape(c)}</td>" for c in row)
            body_rows.append(f"<tr>{cells}</tr>")
        table_html = (
            f"<table><caption>Extracted Chart Data</caption>"
            f"<thead><tr>{headers}</tr></thead>"
            f"<tbody>{''.join(body_rows)}</tbody></table>"
        )

    ocr_block = (
        f"<p><strong>Transcribed Text in Image:</strong> {html.escape(fig.extracted_ocr_text)}</p>"
        if fig.extracted_ocr_text
        else ""
    )

    return (
        f"<figure role='group' aria-describedby='{desc_id}'>\n"
        f"  <img src='{html.escape(image_src)}' alt='{safe_alt}' />\n"
        f"  <details id='{desc_id}'>\n"
        f"    <summary>Extended Description for Screen Readers</summary>\n"
        f"    <p>{safe_detail}</p>\n"
        f"    {ocr_block}\n"
        f"    {table_html}\n"
        f"  </details>\n"
        f"</figure>"
    )

from app.wcag_validator import compute_wcag_contrast_ratio, validate_heading_hierarchy
from app.accessible_html_builder import AccessibleFigureDescription, render_accessible_figure_html

def test_wcag_contrast_ratio_calculation():
    # Dark navy (#0F172A) on pure white (#FFFFFF) -> high contrast AAA pass
    ratio, aa, aaa = compute_wcag_contrast_ratio("#0F172A", "#FFFFFF")
    assert ratio > 15.0
    assert aa is True and aaa is True

    # Light grey (#94A3B8) on white (#FFFFFF) -> fails WCAG AA 4.5:1
    low_ratio, low_aa, _ = compute_wcag_contrast_ratio("#94A3B8", "#FFFFFF")
    assert low_ratio < 4.5
    assert low_aa is False

def test_heading_hierarchy_validation():
    assert validate_heading_hierarchy([1, 2, 2, 3, 2]) == []
    errors = validate_heading_hierarchy([1, 4])
    assert len(errors) == 1
    assert "Skipped heading level from H1 to H4" in errors[0]

def test_accessible_figure_html_renders_alt_and_table_scope():
    fig = AccessibleFigureDescription(
        figure_id="chart-q4",
        concise_alt_text="Bar chart showing Q1 to Q4 revenue growth from $1.2M to $2.1M.",
        detailed_spatial_description="Vertical bar chart with four bars increasing steadily across quarters.",
        extracted_ocr_text="FY2026 Quarterly Revenue ($M)",
        chart_data_rows=[["Quarter", "Revenue ($M)"], ["Q1", "1.2"], ["Q4", "2.1"]],
    )
    rendered = render_accessible_figure_html(fig, "chart-q4.png")
    assert "alt='Bar chart showing Q1 to Q4 revenue growth from $1.2M to $2.1M.'" in rendered
    assert "aria-describedby='desc-chart-q4'" in rendered
    assert "<th scope='col'>Quarter</th>" in rendered