@mcptoolshop/accessibility-suite 0.1.0

package/src/a11y-assist/a11y_assist/profiles/cognitive_load.py

@@ -0,0 +1,245 @@
+"""Cognitive-load profile transformation.
+
+Transforms AssistResult for users who benefit from reduced cognitive load:
+- ADHD / executive dysfunction
+- Autism / sensory overload
+- Anxiety under incident conditions
+- Novices under stress
+
+Invariants (non-negotiable):
+1. No invented facts - only rephrases existing content
+2. No invented commands - SAFE commands must be verbatim from input
+3. SAFE-only remains absolute
+4. Additive behavior - doesn't rewrite original output
+5. Deterministic - no randomness, no network calls
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List, Optional
+
+from ..render import AssistResult, Confidence
+
+# Boilerplate prefixes to strip
+BOILERPLATE_PREFIXES = re.compile(
+    r"^(re-?run:\s*|run:\s*|try:\s*|\$\s*|>\s*)", re.IGNORECASE
+)
+
+# Phrases to rewrite to imperative form
+IMPERATIVE_REWRITES = [
+    (re.compile(r"^you should\s+", re.IGNORECASE), "Do "),
+    (re.compile(r"^please\s+", re.IGNORECASE), "Do "),
+    (re.compile(r"^consider\s+", re.IGNORECASE), "Try "),
+    (re.compile(r"^it may help to\s+", re.IGNORECASE), "Try "),
+]
+
+# Conjunction replacements
+CONJUNCTION_REPLACEMENTS = [
+    (" and then ", ". Then "),
+    (" and ", ". "),
+    (" but ", ". "),
+]
+
+# Parenthetical patterns
+PARENTHETICAL_RE = re.compile(r"\s*[\(\[][^\)\]]*[\)\]]\s*")
+
+# Max step length
+MAX_STEP_LENGTH = 90
+
+
+def _strip_boilerplate(s: str) -> str:
+    """Strip boilerplate prefixes from a string."""
+    return BOILERPLATE_PREFIXES.sub("", s).strip()
+
+
+def _remove_parentheticals(s: str) -> str:
+    """Remove parenthetical content (...) and [...] from string."""
+    result = PARENTHETICAL_RE.sub(" ", s).strip()
+    # If removal empties the string, revert
+    if not result:
+        return s
+    # Clean up double spaces
+    return re.sub(r"\s+", " ", result)
+
+
+def _to_imperative(s: str) -> str:
+    """Convert phrases to imperative form."""
+    for pattern, replacement in IMPERATIVE_REWRITES:
+        s = pattern.sub(replacement, s)
+    return s
+
+
+def _reduce_conjunctions(s: str) -> str:
+    """Replace conjunctions, keep only first sentence."""
+    for old, new in CONJUNCTION_REPLACEMENTS:
+        s = s.replace(old, new)
+
+    # Keep only first sentence
+    sentences = s.split(". ")
+    if sentences:
+        first = sentences[0].strip()
+        if first and not first.endswith("."):
+            first += "."
+        return first
+    return s
+
+
+def _cap_length(s: str, max_len: int = MAX_STEP_LENGTH) -> str:
+    """Cap string length, truncating with ellipsis if needed."""
+    if len(s) <= max_len:
+        return s
+    return s[: max_len - 1] + "…"
+
+
+def normalize_step(step: str) -> str:
+    """Normalize a single step according to cognitive-load rules.
+
+    Order of operations:
+    1. Strip boilerplate prefixes
+    2. Remove parentheticals
+    3. Convert to imperative form
+    4. Reduce conjunctions (keep first sentence)
+    5. Cap length at 90 chars
+    """
+    s = step.strip()
+    if not s:
+        return s
+
+    # 1. Strip boilerplate
+    s = _strip_boilerplate(s)
+
+    # 2. Remove parentheticals
+    s = _remove_parentheticals(s)
+
+    # 3. Convert to imperative
+    s = _to_imperative(s)
+
+    # 4. Reduce conjunctions
+    s = _reduce_conjunctions(s)
+
+    # 5. Cap length
+    s = _cap_length(s)
+
+    return s
+
+
+def normalize_safest_step(s: str) -> str:
+    """Normalize safest_next_step for cognitive-load.
+
+    - Remove parentheticals
+    - Remove subordinate clauses (split on ; or ,)
+    - Ensure ends with period
+    - One sentence max
+    """
+    if not s:
+        return "Follow the Fix steps."
+
+    # Remove parentheticals
+    s = _remove_parentheticals(s)
+
+    # Split on semicolon or comma, keep first segment
+    for sep in [";", ","]:
+        if sep in s:
+            s = s.split(sep)[0].strip()
+            break
+
+    # Reduce conjunctions to get one sentence
+    s = _reduce_conjunctions(s)
+
+    # Ensure ends with period
+    s = s.strip()
+    if s and not s.endswith("."):
+        s += "."
+
+    return _cap_length(s, MAX_STEP_LENGTH)
+
+
+def reduce_plan(plan: List[str], max_steps: int = 3) -> List[str]:
+    """Reduce plan to max_steps normalized items.
+
+    No merging, no summarization beyond normalization.
+    """
+    if not plan:
+        return ["Follow the tool's Fix steps in order."]
+
+    normalized = [normalize_step(s) for s in plan if s.strip()]
+    # Filter out empty results
+    normalized = [s for s in normalized if s]
+
+    if not normalized:
+        return ["Follow the tool's Fix steps in order."]
+
+    return normalized[:max_steps]
+
+
+def select_safe_command(
+    commands: List[str], confidence: Confidence
+) -> Optional[str]:
+    """Select at most one SAFE command for cognitive-load.
+
+    Rules:
+    - Only include if confidence is High or Medium
+    - Return first command only
+    - No command synthesis
+    """
+    if confidence == "Low":
+        return None
+
+    if not commands:
+        return None
+
+    # Return first command, no modification (must be verbatim)
+    return commands[0]
+
+
+def reduce_notes(notes: List[str], max_notes: int = 2) -> List[str]:
+    """Reduce notes to max_notes, remove parentheticals, cap length."""
+    if not notes:
+        return []
+
+    reduced = []
+    for note in notes[:max_notes]:
+        n = _remove_parentheticals(note)
+        n = _cap_length(n, 100)
+        if n:
+            reduced.append(n)
+
+    return reduced
+
+
+def apply_cognitive_load(result: AssistResult) -> AssistResult:
+    """Transform AssistResult for cognitive-load profile.
+
+    This transformation:
+    1. Reduces plan to exactly 3 steps max
+    2. Normalizes step language (no conjunctions, parentheticals)
+    3. Selects at most 1 SAFE command (none if Low confidence)
+    4. Reduces notes to 2 max
+
+    Invariants enforced:
+    - No invented facts (only rephrases existing content)
+    - No invented commands (SAFE commands verbatim from input)
+    - Deterministic output
+    """
+    # Reduce and normalize plan
+    reduced_plan = reduce_plan(result.plan)
+
+    # Normalize safest next step
+    normalized_safest = normalize_safest_step(result.safest_next_step)
+
+    # Select single SAFE command (or None)
+    safe_cmd = select_safe_command(result.next_safe_commands, result.confidence)
+    safe_commands = [safe_cmd] if safe_cmd else []
+
+    # Reduce notes
+    reduced_notes = reduce_notes(result.notes)
+
+    return AssistResult(
+        anchored_id=result.anchored_id,
+        confidence=result.confidence,
+        safest_next_step=normalized_safest,
+        plan=reduced_plan,
+        next_safe_commands=safe_commands,
+        notes=reduced_notes,
+    )

package/src/a11y-assist/a11y_assist/profiles/cognitive_load_render.py

@@ -0,0 +1,86 @@
+"""Cognitive-load profile renderer.
+
+Renders AssistResult with cognitive-load specific formatting:
+- Goal line at top
+- First/Next/Last labels instead of numbers
+- Maximum clarity and brevity
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from ..render import AssistResult
+
+# Step labels for cognitive-load profile
+STEP_LABELS = ["First", "Next", "Last"]
+
+
+def render_cognitive_load(result: AssistResult) -> str:
+    """Render an AssistResult in cognitive-load format.
+
+    Format:
+        ASSIST (Cognitive Load):
+        - Anchored to: ID or (none)
+        - Confidence: High/Medium/Low
+
+        Goal: Get back to a known-good state.
+
+        Safest next step:
+          <step>
+
+        Plan:
+          First: <step>
+          Next: <step>
+          Last: <step>
+
+        Next (SAFE):
+          <command>   (only if confidence is High or Medium)
+
+        Notes:
+          - note
+    """
+    lines: List[str] = []
+
+    # Header
+    lines.append("ASSIST (Cognitive Load):")
+
+    if result.anchored_id:
+        lines.append(f"- Anchored to: {result.anchored_id}")
+    else:
+        lines.append("- Anchored to: (none)")
+
+    lines.append(f"- Confidence: {result.confidence}")
+    lines.append("")
+
+    # Goal (fixed text)
+    lines.append("Goal: Get back to a known-good state.")
+    lines.append("")
+
+    # Safest next step
+    lines.append("Safest next step:")
+    lines.append(f"  {result.safest_next_step}")
+    lines.append("")
+
+    # Plan with First/Next/Last labels
+    lines.append("Plan:")
+    for i, step in enumerate(result.plan[:3]):
+        label = STEP_LABELS[i] if i < len(STEP_LABELS) else f"Step {i + 1}"
+        lines.append(f"  {label}: {step}")
+
+    # Next (SAFE) - only show if commands exist
+    # Note: cognitive-load transform already filters for confidence
+    if result.next_safe_commands:
+        lines.append("")
+        lines.append("Next (SAFE):")
+        # Only show first command for cognitive-load
+        lines.append(f"  {result.next_safe_commands[0]}")
+
+    # Notes (max 2, already reduced by transform)
+    if result.notes:
+        lines.append("")
+        lines.append("Notes:")
+        for note in result.notes[:2]:
+            lines.append(f"  - {note}")
+
+    return "\n".join(lines) + "\n"

package/src/a11y-assist/a11y_assist/profiles/dyslexia.py

@@ -0,0 +1,144 @@
+"""Dyslexia profile transform.
+
+Reduces reading friction without reducing information:
+- Extra vertical spacing between sections
+- One idea per line
+- No dense paragraphs
+- No italics/all-caps emphasis
+- Labels always explicit
+- No parentheticals
+- No symbolic emphasis
+- Abbreviations expanded once
+
+Max 5 steps. Confidence preserved or downgraded.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List
+
+from ..render import AssistResult
+
+# Abbreviation expansions (letter-spelled for clarity)
+ABBREVIATIONS = {
+    r"\bCLI\b": "command line",
+    r"\bID\b": "I D",
+    r"\bJSON\b": "J S O N",
+    r"\bAPI\b": "A P I",
+    r"\bSFTP\b": "S F T P",
+    r"\bSSH\b": "S S H",
+    r"\bURL\b": "U R L",
+    r"\bHTTP\b": "H T T P",
+    r"\bHTTPS\b": "H T T P S",
+}
+
+# Parenthetical pattern
+PARENTHETICAL = re.compile(r"\s*[\(\[][^\)\]]*[\)\]]\s*")
+
+# Visual reference pattern
+VISUAL_REF = re.compile(r"\b(see\s+)?(above|below|left|right|arrow)\b", re.IGNORECASE)
+
+# Symbolic emphasis pattern (*, _, →, emojis)
+SYMBOLIC_EMPHASIS = re.compile(r"[*_→←↑↓]|[\U0001F300-\U0001F9FF]")
+
+
+def _expand_abbreviations(text: str) -> str:
+    """Expand abbreviations once for readability."""
+    result = text
+    for pattern, expansion in ABBREVIATIONS.items():
+        result = re.sub(pattern, expansion, result, count=1)
+    return result
+
+
+def _remove_parentheticals(text: str) -> str:
+    """Remove parenthetical content."""
+    return PARENTHETICAL.sub(" ", text).strip()
+
+
+def _remove_visual_refs(text: str) -> str:
+    """Remove visual navigation references."""
+    return VISUAL_REF.sub("", text).strip()
+
+
+def _remove_symbolic_emphasis(text: str) -> str:
+    """Remove symbolic emphasis characters."""
+    return SYMBOLIC_EMPHASIS.sub("", text).strip()
+
+
+def _normalize_step(step: str) -> str:
+    """Normalize a step for dyslexia profile.
+
+    - Remove parentheticals
+    - Remove visual references
+    - Remove symbolic emphasis
+    - Expand abbreviations
+    - Truncate to 110 chars
+    """
+    result = step
+    result = _remove_parentheticals(result)
+    result = _remove_visual_refs(result)
+    result = _remove_symbolic_emphasis(result)
+    result = _expand_abbreviations(result)
+
+    # Clean up multiple spaces
+    result = re.sub(r"\s+", " ", result).strip()
+
+    # Truncate if too long
+    if len(result) > 110:
+        result = result[:107] + "..."
+
+    return result
+
+
+def _normalize_safest_step(text: str) -> str:
+    """Normalize safest next step."""
+    result = _remove_parentheticals(text)
+    result = _remove_visual_refs(result)
+    result = _remove_symbolic_emphasis(result)
+    result = _expand_abbreviations(result)
+    result = re.sub(r"\s+", " ", result).strip()
+    return result
+
+
+def apply_dyslexia(result: AssistResult) -> AssistResult:
+    """Apply dyslexia profile transformation.
+
+    - Expand abbreviations
+    - Remove parentheticals
+    - Remove visual references
+    - Remove symbolic emphasis
+    - Max 5 steps
+    - Preserve or downgrade confidence
+    """
+    # Normalize safest next step
+    safest = _normalize_safest_step(result.safest_next_step)
+
+    # Normalize and limit plan steps
+    plan: List[str] = []
+    for step in result.plan[:5]:  # Max 5 steps
+        normalized = _normalize_step(step)
+        if normalized:
+            plan.append(normalized)
+
+    # Normalize notes (max 2)
+    notes: List[str] = []
+    for note in result.notes[:2]:  # Max 2 notes
+        normalized = _remove_parentheticals(note)
+        normalized = _remove_symbolic_emphasis(normalized)
+        normalized = _expand_abbreviations(normalized)
+        normalized = re.sub(r"\s+", " ", normalized).strip()
+        if normalized:
+            notes.append(normalized)
+
+    # Commands: preserve only safe commands, max 3
+    commands = result.next_safe_commands[:3]
+
+    return AssistResult(
+        anchored_id=result.anchored_id,
+        confidence=result.confidence,  # Preserved (guard enforces no increase)
+        safest_next_step=safest,
+        plan=plan,
+        next_safe_commands=commands,
+        notes=notes,
+    )

package/src/a11y-assist/a11y_assist/profiles/dyslexia_render.py

@@ -0,0 +1,77 @@
+"""Dyslexia profile renderer.
+
+Output format optimized for reduced reading friction:
+- Extra vertical spacing between sections
+- One idea per line
+- Explicit labels
+- Numbered steps with "Step N:" prefix
+- No dense paragraphs
+"""
+
+from __future__ import annotations
+
+from ..render import AssistResult
+
+
+def render_dyslexia(result: AssistResult) -> str:
+    """Render AssistResult in dyslexia-friendly format.
+
+    Format:
+    ASSIST (Dyslexia):
+    Anchored ID: <ID or none>
+    Confidence: High | Medium | Low
+
+    Summary:
+    <derived from context>
+
+    Safest next step:
+    <one sentence>
+
+    Plan:
+    - Step 1: <sentence>
+    - Step 2: <sentence>
+    ...
+
+    Next safe command:
+    <command>
+
+    Notes:
+    - <sentence>
+    """
+    lines = []
+
+    # Header - each piece on its own line
+    lines.append("ASSIST (Dyslexia):")
+    lines.append("")
+    lines.append(f"Anchored ID: {result.anchored_id or 'none'}")
+    lines.append("")
+    lines.append(f"Confidence: {result.confidence}")
+    lines.append("")
+
+    # Safest next step - explicit label
+    lines.append("Safest next step:")
+    lines.append(f"  {result.safest_next_step}")
+    lines.append("")
+
+    # Plan - numbered with "Step N:" prefix
+    if result.plan:
+        lines.append("Plan:")
+        for i, step in enumerate(result.plan, 1):
+            lines.append(f"  - Step {i}: {step}")
+        lines.append("")
+
+    # Next safe command - only if confidence is not Low
+    if result.next_safe_commands and result.confidence != "Low":
+        lines.append("Next safe command:")
+        # Show first command only for simplicity
+        lines.append(f"  {result.next_safe_commands[0]}")
+        lines.append("")
+
+    # Notes - max 2, each on its own line
+    if result.notes:
+        lines.append("Notes:")
+        for note in result.notes[:2]:
+            lines.append(f"  - {note}")
+        lines.append("")
+
+    return "\n".join(lines)

package/src/a11y-assist/a11y_assist/profiles/plain_language.py

@@ -0,0 +1,119 @@
+"""Plain-language profile transform.
+
+Maximizes understandability through:
+- Active voice
+- Present tense
+- One clause per sentence
+- No idioms or metaphors
+- No jargon unless already present
+- Short, clear sentences
+
+Max 4 steps. Confidence preserved or downgraded.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List
+
+from ..render import AssistResult
+
+# Parenthetical pattern
+PARENTHETICAL = re.compile(r"\s*[\(\[][^\)\]]*[\)\]]\s*")
+
+# Conjunction pattern for splitting
+CONJUNCTIONS = re.compile(r"\s*(?:,\s*and\s+|,\s*but\s+|,\s*or\s+|\s+and\s+|\s+but\s+|\s+or\s+)")
+
+# Subordinate clause starters
+SUBORDINATE = re.compile(
+    r"\s*(?:,\s*)?(?:which|that|who|whom|whose|when|where|while|although|because|if|unless|until|after|before|since)\s+.*$",
+    re.IGNORECASE,
+)
+
+
+def _remove_parentheticals(text: str) -> str:
+    """Remove parenthetical content."""
+    return PARENTHETICAL.sub(" ", text).strip()
+
+
+def _simplify_sentence(text: str) -> str:
+    """Simplify a sentence to one clause.
+
+    - Remove parentheticals
+    - Split on conjunctions, keep first clause
+    - Remove subordinate clauses
+    """
+    result = _remove_parentheticals(text)
+
+    # Split on conjunctions, keep first part
+    parts = CONJUNCTIONS.split(result, maxsplit=1)
+    if parts:
+        result = parts[0].strip()
+
+    # Remove subordinate clauses
+    result = SUBORDINATE.sub("", result).strip()
+
+    # Clean up trailing punctuation issues
+    result = re.sub(r"\s+", " ", result).strip()
+
+    # Ensure ends with period if it doesn't have punctuation
+    if result and not result[-1] in ".!?:":
+        result = result + "."
+
+    return result
+
+
+def _normalize_step(step: str) -> str:
+    """Normalize a step for plain-language profile.
+
+    - Simplify to one clause
+    - Remove complex structures
+    """
+    result = _simplify_sentence(step)
+
+    # Remove any remaining parentheticals
+    result = _remove_parentheticals(result)
+
+    # Clean up
+    result = re.sub(r"\s+", " ", result).strip()
+
+    return result
+
+
+def apply_plain_language(result: AssistResult) -> AssistResult:
+    """Apply plain-language profile transformation.
+
+    - Simplify sentences to one clause
+    - Remove parentheticals
+    - Remove subordinate clauses
+    - Max 4 steps
+    - Preserve or downgrade confidence
+    """
+    # Simplify safest next step
+    safest = _simplify_sentence(result.safest_next_step)
+
+    # Normalize and limit plan steps
+    plan: List[str] = []
+    for step in result.plan[:4]:  # Max 4 steps
+        normalized = _normalize_step(step)
+        if normalized and len(normalized) > 2:  # Skip trivially empty
+            plan.append(normalized)
+
+    # Simplify notes (max 2)
+    notes: List[str] = []
+    for note in result.notes[:2]:
+        simplified = _simplify_sentence(note)
+        if simplified and len(simplified) > 2:
+            notes.append(simplified)
+
+    # Commands: preserve only safe commands, max 1 for simplicity
+    commands = result.next_safe_commands[:1]
+
+    return AssistResult(
+        anchored_id=result.anchored_id,
+        confidence=result.confidence,  # Preserved (guard enforces no increase)
+        safest_next_step=safest,
+        plan=plan,
+        next_safe_commands=commands,
+        notes=notes,
+    )