# MiroFish v2: Grade-Level Accessibility Analysis

## The Core Insight

**What InceptBench already does well:** LLM-based content quality, distractor analysis, standard alignment.

**What it CAN'T do:** Tell you if a 3rd grader can even READ the question.

**MiroFish's unique value:** Grade-appropriate accessibility analysis.

A rowdy 3rd grader trying to read "What is the primary function of the Electoral College in ratifying presidential elections?" doesn't just "know less" - they:
- Don't know "electoral", "ratifying", "primary function"
- Can't parse a 15-word sentence with multiple clauses
- Have never heard of the Electoral College
- Will pick randomly or the shortest answer

**This is measurable and actionable.** Unlike "would students get this right?" (speculative), we can objectively say "this question requires grade 9 vocabulary but targets grade 5."

---

## The Output (What InceptBench Gets)

```json
{
  "target_grade": 5,
  "accessibility_verdict": "too_advanced",
  "accessibility_score": 0.35,

  "reading_level": {
    "measured_grade": 8.2,
    "target_grade": 5,
    "gap": 3.2,
    "verdict": "too_advanced",
    "components": {
      "flesch_kincaid": 8.2,
      "avg_sentence_length": 18.5,
      "avg_syllables_per_word": 1.9
    }
  },

  "vocabulary_issues": [
    {
      "word": "constitutional",
      "grade_introduced": 8,
      "target_grade": 5,
      "gap": 3,
      "suggestion": "part of the Constitution",
      "context": "...the constitutional amendment..."
    },
    {
      "word": "ratify",
      "grade_introduced": 9,
      "target_grade": 5,
      "gap": 4,
      "suggestion": "approve" | "officially accept",
      "context": "...ratifying the decision..."
    }
  ],

  "sentence_issues": [
    {
      "sentence": "The Electoral College, which was established by the Constitution, serves as the formal body that elects the President.",
      "word_count": 19,
      "recommended_max": 12,
      "issue": "too_long",
      "clauses": 2,
      "suggestion": "Split into two sentences"
    }
  ],

  "prior_knowledge": {
    "required_concepts": ["Electoral College", "presidential election process", "voting"],
    "concepts_by_grade": {
      "Electoral College": {"typically_taught": 8, "target": 5, "gap": 3},
      "voting": {"typically_taught": 3, "target": 5, "gap": 0}
    },
    "verdict": "requires_advanced_knowledge"
  },

  "cognitive_load": {
    "steps_to_answer": 3,
    "working_memory_items": 4,
    "grade_appropriate_max": 2,
    "verdict": "too_complex"
  },

  "recommendations": [
    {
      "priority": "high",
      "type": "vocabulary",
      "issue": "Word 'constitutional' requires grade 8, target is grade 5",
      "fix": "Replace with 'part of the Constitution' or 'in the Constitution'"
    },
    {
      "priority": "high",
      "type": "sentence_structure",
      "issue": "Sentence has 19 words with embedded clause",
      "fix": "Split: 'The Constitution created the Electoral College. This group officially elects the President.'"
    },
    {
      "priority": "medium",
      "type": "prior_knowledge",
      "issue": "Electoral College not typically taught until grade 8",
      "fix": "Add context or scaffold: 'The Electoral College is a group of people who vote for President...'"
    }
  ],

  "archetype_modifiers": {
    "esl_student": {
      "accessibility_score": 0.15,
      "additional_barriers": [
        "Idiom: 'checks and balances' (not literal)",
        "Cultural knowledge: US-specific government structure"
      ]
    },
    "class_clown": {
      "accessibility_score": 0.20,
      "additional_barriers": [
        "Long question reduces engagement",
        "Abstract topic loses attention"
      ]
    }
  },

  "rewritten_version": {
    "grade_5_accessible": {
      "text": "What does the Electoral College do? (The Electoral College is a group of people who help choose the President.)",
      "reading_level": 4.8,
      "changes_made": [
        "Simplified vocabulary",
        "Added context in parentheses",
        "Shortened sentence"
      ]
    }
  }
}
```

---

## Why This Is The Best Integration

### 1. It's ACTIONABLE
- Not "this question is hard" but "replace 'ratify' with 'approve'"
- Content authors can immediately fix issues
- Machine-readable for automated content pipelines

### 2. It's OBJECTIVE
- Flesch-Kincaid is a formula, not a vibe
- Vocabulary grade levels come from established educational research
- Sentence length thresholds are evidence-based

### 3. It's UNIQUE
- InceptBench's LLM eval can't calculate reading levels
- Standard LLMs don't have grade-level vocabulary databases
- This is the missing piece in content accessibility

### 4. It Catches Real Problems
- Textbook authors routinely write above grade level
- "Simplified" content often still uses advanced vocabulary
- Questions appropriate for content may not be appropriate for assessment

---

## Implementation Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    AccessibilityAnalyzer                        │
│                    (Main Entry Point)                           │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│ ReadingLevel  │    │  Vocabulary   │    │ PriorKnowledge│
│   Analyzer    │    │   Analyzer    │    │   Analyzer    │
│               │    │               │    │               │
│ • Flesch-     │    │ • Word→Grade  │    │ • Concept     │
│   Kincaid     │    │   mapping     │    │   extraction  │
│ • Sentence    │    │ • Suggestions │    │ • Curriculum  │
│   complexity  │    │   database    │    │   mapping     │
│ • Syllable    │    │ • Context-    │    │ • Standards   │
│   counting    │    │   aware       │    │   database    │
└───────────────┘    └───────────────┘    └───────────────┘
        │                     │                     │
        └─────────────────────┼─────────────────────┘
                              ▼
                    ┌───────────────┐
                    │CognitiveLoad  │
                    │  Analyzer     │
                    │               │
                    │ • Step count  │
                    │ • Working     │
                    │   memory      │
                    │ • Age norms   │
                    └───────────────┘
                              │
                              ▼
                    ┌───────────────┐
                    │ Archetype     │
                    │ Modifiers     │
                    │               │
                    │ • ESL impact  │
                    │ • Attention   │
                    │ • Engagement  │
                    └───────────────┘
                              │
                              ▼
                    ┌───────────────┐
                    │ Recommendation│
                    │   Engine      │
                    │               │
                    │ • Vocab subs  │
                    │ • Rewrites    │
                    │ • Scaffolding │
                    └───────────────┘
```

---

## Phase 1: Reading Level Engine (Foundation)

**File:** `accessibility/reading_level.py`

### Flesch-Kincaid Implementation
```python
def flesch_kincaid_grade(text: str) -> float:
    """Calculate Flesch-Kincaid grade level."""
    sentences = count_sentences(text)
    words = count_words(text)
    syllables = count_syllables(text)

    # FK Grade Level formula
    return 0.39 * (words / sentences) + 11.8 * (syllables / words) - 15.59
```

### Sentence Complexity Analysis
```python
@dataclass
class SentenceAnalysis:
    text: str
    word_count: int
    clause_count: int
    max_depth: int  # Nesting depth
    has_passive_voice: bool
    grade_appropriate: bool

# Grade-appropriate sentence length thresholds (research-based)
SENTENCE_LENGTH_THRESHOLDS = {
    3: 8,   # 3rd graders: max 8 words
    4: 10,
    5: 12,
    6: 14,
    7: 16,
    8: 18,
    9: 20,
    10: 22,
    11: 25,
    12: 28,
}
```

---

## Phase 2: Vocabulary Database

**File:** `accessibility/vocabulary.py`

### The Critical Resource: Word→Grade Mapping

This is the most important component. We need a database of ~10,000+ common words mapped to the grade level where they're typically introduced.

**Sources:**
1. **Dolch Word List** - Basic sight words (K-3)
2. **Fry Word List** - 1000 most common words by grade
3. **Academic Word List (AWL)** - Academic vocabulary (grades 6-12)
4. **CCSS Vocabulary** - Standards-aligned vocabulary by grade
5. **Dale-Chall Word List** - 3000 words known by 4th graders

**Structure:**
```python
@dataclass
class VocabularyEntry:
    word: str
    grade_introduced: int
    subject_specific: Optional[str]  # "math", "science", etc.
    alternatives: List[str]  # Simpler synonyms
    definition_simple: str  # Kid-friendly definition

VOCABULARY_DATABASE: Dict[str, VocabularyEntry] = {
    "constitutional": VocabularyEntry(
        word="constitutional",
        grade_introduced=8,
        subject_specific="social_studies",
        alternatives=["about the Constitution", "in the Constitution"],
        definition_simple="related to the Constitution, the main set of rules for the US government"
    ),
    "ratify": VocabularyEntry(
        word="ratify",
        grade_introduced=9,
        subject_specific="social_studies",
        alternatives=["approve", "officially accept", "agree to"],
        definition_simple="to officially approve or agree to something"
    ),
    "photosynthesis": VocabularyEntry(
        word="photosynthesis",
        grade_introduced=5,
        subject_specific="science",
        alternatives=["how plants make food"],
        definition_simple="the way plants use sunlight to make their own food"
    ),
    # ... thousands more
}
```

### Building the Database

**Option A: Curated (Higher quality, more work)**
- Start with existing grade-leveled lists
- Add subject-specific vocabulary from standards
- Manual review for accuracy

**Option B: LLM-assisted (Faster, needs validation)**
```python
async def estimate_grade_level(word: str, context: str = None) -> int:
    """Use LLM to estimate when a word is typically introduced."""
    prompt = f"""What grade level (K-12) would a US student typically
    first learn the word "{word}"?

    Consider:
    - When it appears in curriculum
    - Reading complexity
    - Abstract vs concrete concepts

    Return just the number (e.g., "5" for 5th grade)."""

    # LLM call...
```

**Option C: Hybrid (Recommended)**
- Use established lists as foundation
- LLM fills gaps for domain-specific terms
- Human validation for edge cases
- Continuous improvement from usage

---

## Phase 3: Prior Knowledge Mapping

**File:** `accessibility/prior_knowledge.py`

### Concept Extraction
```python
async def extract_required_concepts(content: Dict) -> List[Concept]:
    """Extract concepts a student must know to answer this question."""

    prompt = f"""Analyze this question and list ALL prior knowledge
    a student needs to answer it correctly.

    Question: {content['text']}
    Options: {content['options']}

    List specific concepts, not general skills:
    - BAD: "reading comprehension"
    - GOOD: "Electoral College elects the President"
    - GOOD: "There are 538 electors"

    Return JSON: {{"required_concepts": ["concept1", "concept2", ...]}}"""
```

### Curriculum Standards Database
```python
# When concepts are typically taught (US curriculum)
CONCEPT_GRADE_LEVELS = {
    # Civics/Government
    "three branches of government": 4,
    "checks and balances": 5,
    "Electoral College": 8,
    "faithless electors": 11,  # AP level
    "12th Amendment": 11,

    # Math
    "addition": 1,
    "multiplication": 3,
    "fractions": 3,
    "negative numbers": 6,
    "quadratic formula": 9,
    "derivatives": 11,

    # Science
    "states of matter": 4,
    "photosynthesis": 5,
    "cells": 6,
    "DNA": 7,
    "evolution": 8,
    "quantum mechanics": 12,
}

# Map to actual standards (CCSS, NGSS, etc.)
CONCEPT_TO_STANDARD = {
    "Electoral College": "CCSS.ELA-LITERACY.RH.9-10.3",
    "quadratic formula": "CCSS.MATH.CONTENT.HSA.REI.B.4",
}
```

---

## Phase 4: Cognitive Load Assessment

**File:** `accessibility/cognitive_load.py`

### What We're Measuring

1. **Steps to Answer**: How many mental operations?
2. **Working Memory Load**: How many things to hold in mind?
3. **Abstraction Level**: Concrete vs abstract reasoning?

### Age-Appropriate Thresholds

Based on cognitive development research:

```python
COGNITIVE_THRESHOLDS = {
    # Grade: (max_steps, max_working_memory, abstraction_ok)
    3: (2, 2, False),   # 3rd graders: 2 steps, 2 items, concrete only
    4: (2, 3, False),
    5: (3, 3, True),    # Can handle some abstraction
    6: (3, 4, True),
    7: (4, 4, True),
    8: (4, 5, True),
    9: (5, 5, True),
    10: (5, 6, True),
    11: (6, 6, True),
    12: (6, 7, True),
}
```

### Analysis
```python
async def analyze_cognitive_load(content: Dict) -> CognitiveLoadAnalysis:
    """Analyze the cognitive demands of answering this question."""

    prompt = f"""Analyze the cognitive load of this question.

    Question: {content['text']}
    Options: {content['options']}

    Determine:
    1. Steps to answer: How many distinct mental operations?
       (e.g., "recall fact" = 1, "compare two things" = 1, "apply formula" = 1)

    2. Working memory items: How many pieces of info to hold simultaneously?
       (e.g., remembering numbers while calculating)

    3. Abstraction level: Is this concrete or abstract?
       - Concrete: "What color is the sky?"
       - Abstract: "What is the relationship between X and Y?"

    Return JSON:
    {{
        "steps": [
            {{"action": "recall", "content": "what Electoral College does"}},
            {{"action": "compare", "content": "match to answer options"}}
        ],
        "working_memory_items": ["Electoral College definition", "4 answer options"],
        "abstraction_level": "abstract",
        "reasoning": "..."
    }}"""
```

---

## Phase 5: Recommendation Engine

**File:** `accessibility/recommendations.py`

### Vocabulary Simplification
```python
def suggest_vocabulary_replacements(
    text: str,
    vocabulary_issues: List[VocabularyIssue],
) -> List[Recommendation]:
    """Generate specific replacement suggestions."""

    recommendations = []
    for issue in vocabulary_issues:
        word = issue.word
        entry = VOCABULARY_DATABASE.get(word.lower())

        if entry and entry.alternatives:
            recommendations.append(Recommendation(
                priority="high" if issue.gap > 3 else "medium",
                type="vocabulary",
                issue=f"'{word}' requires grade {entry.grade_introduced}, target is grade {issue.target_grade}",
                fix=f"Replace with: {' or '.join(entry.alternatives)}",
                example=text.replace(word, entry.alternatives[0])
            ))

    return recommendations
```

### Sentence Restructuring
```python
async def suggest_sentence_restructure(
    sentence: str,
    target_grade: int,
) -> str:
    """Use LLM to suggest a grade-appropriate rewrite."""

    max_words = SENTENCE_LENGTH_THRESHOLDS[target_grade]

    prompt = f"""Rewrite this sentence for a grade {target_grade} student.

    Original: {sentence}

    Requirements:
    - Maximum {max_words} words per sentence (can split into multiple)
    - Use grade {target_grade} vocabulary
    - Keep the same meaning
    - Make it clear and direct

    Return just the rewritten text."""
```

### Full Question Rewrite
```python
async def generate_accessible_version(
    content: Dict,
    target_grade: int,
) -> Dict:
    """Generate a fully accessible version of the question."""

    # This is the premium feature - actual rewrite suggestions
```

---

## Phase 6: Archetype Modifiers

**File:** `accessibility/archetypes.py`

Archetypes modify the base accessibility score:

```python
ARCHETYPE_MODIFIERS = {
    "honors_overachiever": {
        "vocabulary_tolerance": +2,  # Can handle 2 grades above
        "sentence_tolerance": +3,    # Can handle longer sentences
        "attention_bonus": 1.2,      # Reads more carefully
    },
    "esl_student": {
        "vocabulary_tolerance": -2,  # Needs 2 grades below
        "sentence_tolerance": -2,
        "attention_bonus": 0.9,
        "extra_barriers": ["idioms", "cultural_references", "passive_voice"],
    },
    "class_clown": {
        "vocabulary_tolerance": 0,
        "sentence_tolerance": -3,    # Loses focus on long sentences
        "attention_bonus": 0.5,
        "extra_barriers": ["long_questions", "abstract_topics"],
    },
    "disengaged_but_smart": {
        "vocabulary_tolerance": +1,
        "sentence_tolerance": 0,
        "attention_bonus": 0.6,
        "extra_barriers": ["boring_topics", "long_questions"],
    },
}

def apply_archetype_modifier(
    base_accessibility: AccessibilityResult,
    archetype: str,
) -> ArchetypeAccessibility:
    """Calculate accessibility for specific archetype."""

    modifiers = ARCHETYPE_MODIFIERS.get(archetype, {})

    # Adjust vocabulary threshold
    vocab_tolerance = modifiers.get("vocabulary_tolerance", 0)
    adjusted_vocab_score = recalculate_vocab_issues(
        base_accessibility.vocabulary_issues,
        tolerance=vocab_tolerance
    )

    # Check for archetype-specific barriers
    extra_barriers = []
    for barrier in modifiers.get("extra_barriers", []):
        if has_barrier(base_accessibility, barrier):
            extra_barriers.append(describe_barrier(barrier))

    # Calculate final score
    attention = modifiers.get("attention_bonus", 1.0)
    final_score = base_accessibility.score * attention * adjusted_vocab_score

    return ArchetypeAccessibility(
        archetype=archetype,
        accessibility_score=final_score,
        additional_barriers=extra_barriers,
    )
```

---

## File Structure

```
packages/mirofish-simulator/
├── src/mirofish_simulator/
│   ├── __init__.py
│   ├── accessibility/
│   │   ├── __init__.py
│   │   ├── analyzer.py          # Main AccessibilityAnalyzer class
│   │   ├── reading_level.py     # Flesch-Kincaid, sentence analysis
│   │   ├── vocabulary.py        # Word→grade database
│   │   ├── vocabulary_data/
│   │   │   ├── __init__.py
│   │   │   ├── core_words.py    # Dolch, Fry lists
│   │   │   ├── academic.py      # Academic word list
│   │   │   ├── subject_specific.py  # Math, science, social studies
│   │   │   └── suggestions.py   # Replacement suggestions
│   │   ├── prior_knowledge.py   # Concept extraction & curriculum mapping
│   │   ├── cognitive_load.py    # Mental load assessment
│   │   ├── recommendations.py   # Fix suggestions
│   │   └── archetypes.py        # Archetype modifiers
│   ├── simulator.py             # Existing (keep for backward compat)
│   ├── cognition.py             # Existing cognitive models
│   ├── misconceptions.py        # Existing misconception analysis
│   └── comparative.py           # Existing quiz analysis
```

---

## API Design

### Main Entry Point

```python
from mirofish_simulator import AccessibilityAnalyzer

analyzer = AccessibilityAnalyzer(api_key="sk-...")

result = await analyzer.analyze(
    content={
        "text": "What is the primary function of the Electoral College?",
        "options": ["A", "B", "C", "D"],
        "grade": "5",  # Target grade
    },
    include_archetypes=["esl_student", "class_clown"],
    include_rewrite=True,  # Generate accessible rewrite
)

print(f"Accessibility Score: {result.score:.0%}")
print(f"Reading Level: Grade {result.reading_level.measured_grade}")
print(f"Vocabulary Issues: {len(result.vocabulary_issues)}")

for rec in result.recommendations:
    print(f"[{rec.priority}] {rec.fix}")
```

### InceptBench Integration

```python
# In InceptBench evaluation pipeline
from mirofish_simulator import AccessibilityAnalyzer

class ContentEvaluator:
    def __init__(self):
        self.accessibility = AccessibilityAnalyzer()

    async def evaluate(self, content: Dict) -> EvaluationResult:
        # Existing evaluations...
        result = await self.run_standard_evaluations(content)

        # Add accessibility analysis
        if content.get("grade"):
            access = await self.accessibility.analyze(content)
            result["accessibility"] = {
                "score": access.score,
                "verdict": access.verdict,
                "reading_level": access.reading_level.measured_grade,
                "issues": [
                    {"type": "vocabulary", "count": len(access.vocabulary_issues)},
                    {"type": "sentences", "count": len(access.sentence_issues)},
                ],
                "recommendations": [r.to_dict() for r in access.recommendations[:5]],
            }

        return result
```

### CLI

```bash
# Analyze single question
inceptbench accessibility check --question "What is..." --grade 5

# Analyze quiz file
inceptbench accessibility check --file questions.json --grade 5

# Get rewrite suggestions
inceptbench accessibility rewrite --file questions.json --grade 5 --output rewrites.json
```

---

## Building the Vocabulary Database (Critical Path)

This is the most important component. Here's how to build it:

### Step 1: Foundation Lists (Day 1)

```python
# Dolch Basic Sight Words (K-2)
DOLCH_PREPRIMER = ["a", "and", "away", "big", "blue", ...]  # 40 words
DOLCH_PRIMER = ["all", "am", "are", "at", "ate", ...]       # 52 words
DOLCH_GRADE1 = ["after", "again", "an", "any", ...]         # 41 words
DOLCH_GRADE2 = ["always", "around", "because", ...]         # 46 words
DOLCH_GRADE3 = ["about", "better", "bring", ...]            # 41 words

# Map to grades
DOLCH_WORDS = {
    **{w: 0 for w in DOLCH_PREPRIMER},  # Kindergarten
    **{w: 1 for w in DOLCH_PRIMER},
    **{w: 1 for w in DOLCH_GRADE1},
    **{w: 2 for w in DOLCH_GRADE2},
    **{w: 3 for w in DOLCH_GRADE3},
}
```

### Step 2: Academic Word List (Day 1)

```python
# Coxhead Academic Word List - 570 word families
# These are typically introduced in middle/high school
AWL_SUBLIST_1 = [  # Most frequent academic words
    "analyze", "approach", "area", "assess", "assume",
    "authority", "available", "benefit", "concept", "consist",
    "constitute", "context", "contract", "create", "data",
    # ... 60 words total
]

# Map to grades (AWL words are typically grades 6-10)
AWL_GRADES = {
    **{w: 6 for w in AWL_SUBLIST_1[:20]},   # Most common
    **{w: 7 for w in AWL_SUBLIST_1[20:40]},
    **{w: 8 for w in AWL_SUBLIST_1[40:]},
    # ... sublists 2-10 at higher grades
}
```

### Step 3: Subject-Specific Vocabulary (Day 2-3)

```python
# Social Studies / Government
GOVERNMENT_VOCAB = {
    "government": 3,
    "president": 2,
    "vote": 3,
    "election": 4,
    "democracy": 5,
    "congress": 5,
    "constitution": 5,
    "constitutional": 8,
    "amendment": 7,
    "ratify": 9,
    "electoral": 8,
    "electoral college": 8,
    "federalism": 10,
    "bicameral": 11,
    "checks and balances": 5,
    "separation of powers": 6,
    "judicial review": 9,
    "executive branch": 5,
    "legislative branch": 5,
    "supreme court": 5,
}

# Mathematics
MATH_VOCAB = {
    "add": 1,
    "subtract": 1,
    "multiply": 3,
    "divide": 3,
    "fraction": 3,
    "decimal": 4,
    "percent": 5,
    "ratio": 6,
    "proportion": 6,
    "equation": 6,
    "variable": 6,
    "coefficient": 7,
    "polynomial": 9,
    "quadratic": 9,
    "function": 8,
    "derivative": 11,
    "integral": 12,
}

# Science
SCIENCE_VOCAB = {
    "plant": 1,
    "animal": 1,
    "weather": 2,
    "habitat": 3,
    "ecosystem": 5,
    "photosynthesis": 5,
    "cell": 5,
    "organism": 5,
    "atom": 6,
    "molecule": 6,
    "element": 6,
    "compound": 7,
    "chemical reaction": 7,
    "DNA": 7,
    "gene": 8,
    "evolution": 8,
    "hypothesis": 6,
    "theory": 7,
}
```

### Step 4: LLM Gap-Filling (Day 4-5)

For words not in our database, use LLM with caching:

```python
GRADE_LEVEL_CACHE = {}  # Persist to disk

async def get_word_grade_level(word: str) -> int:
    """Get grade level for a word, using cache or LLM."""

    word_lower = word.lower()

    # Check all our databases first
    if word_lower in DOLCH_WORDS:
        return DOLCH_WORDS[word_lower]
    if word_lower in AWL_GRADES:
        return AWL_GRADES[word_lower]
    if word_lower in GOVERNMENT_VOCAB:
        return GOVERNMENT_VOCAB[word_lower]
    # ... other databases

    # Check cache
    if word_lower in GRADE_LEVEL_CACHE:
        return GRADE_LEVEL_CACHE[word_lower]

    # LLM fallback
    grade = await llm_estimate_grade(word)
    GRADE_LEVEL_CACHE[word_lower] = grade

    return grade
```

---

## Success Metrics

### What Makes This Successful

1. **Accuracy**: Reading level calculations match established tools (±0.5 grade levels)
2. **Coverage**: Vocabulary database covers 95% of words in typical assessments
3. **Actionability**: Every flagged issue has a specific fix suggestion
4. **Performance**: Analysis completes in <2 seconds per question

### Validation

```python
# Test against known reading levels
TEST_CASES = [
    # (text, expected_FK_grade)
    ("The cat sat on the mat.", 1.0),
    ("The Electoral College formally elects the President.", 9.2),
    ("Photosynthesis converts light energy into chemical energy.", 10.5),
]

def validate_reading_level():
    for text, expected in TEST_CASES:
        actual = flesch_kincaid_grade(text)
        assert abs(actual - expected) < 1.0, f"FK mismatch: {actual} vs {expected}"
```

---

## Timeline

| Phase | Duration | Deliverable |
|-------|----------|-------------|
| Phase 1: Reading Level Engine | 2 days | FK calculation, sentence analysis |
| Phase 2: Vocabulary Database | 3 days | 5000+ words with grade levels |
| Phase 3: Prior Knowledge | 2 days | Concept extraction, curriculum mapping |
| Phase 4: Cognitive Load | 1 day | Step counting, working memory |
| Phase 5: Recommendations | 2 days | Fix suggestions, rewrites |
| Phase 6: Archetypes | 1 day | Modifier calculations |
| Integration & Testing | 2 days | InceptBench API, CLI |
| **Total** | **~2 weeks** | Production-ready accessibility analysis |

---

## What We're NOT Doing

To stay focused:

1. **Not** predicting exact student scores (speculative)
2. **Not** replacing existing InceptBench evaluators (complementary)
3. **Not** building a full curriculum database (use existing standards)
4. **Not** handling non-English (start with English only)
5. **Not** real-time rewriting (batch processing is fine)

---

## The Bottom Line

**MiroFish v2 = Grade-Level Accessibility Analysis**

One API call tells you:
- Is this question readable by a 5th grader? **No, it's grade 8 level.**
- What's wrong? **3 vocabulary words too advanced, sentences too long**
- How to fix it? **Replace "ratify" with "approve", split the sentence**
- Who struggles most? **ESL students, disengaged learners**

This is the **single best contribution** to InceptBench because it:
1. Provides objective, measurable analysis
2. Gives actionable fix recommendations
3. Catches real problems that content authors miss
4. Complements (doesn't duplicate) existing LLM evaluation
