# MiroFish + InceptBench Integration

## What MiroFish Provides

InceptBench already has LLM-based distractor analysis. MiroFish adds:

### 1. Grade-Level Accessibility Analysis (Reliable)
**Not duplicated by InceptBench**: Deterministic analysis of whether content is readable at target grade.

```python
from mirofish_simulator.accessibility import AccessibilityAnalyzer

analyzer = AccessibilityAnalyzer()
result = await analyzer.analyze(question, target_grade=5)

# Returns:
{
    "reading_level": {
        "flesch_kincaid_grade": 8.3,
        "target_grade": 5,
        "verdict": "too_advanced"  # 3+ grades above
    },
    "vocabulary": {
        "issues": [
            {"word": "ratify", "grade_required": 9, "suggestions": ["approve", "accept"]},
            {"word": "electoral", "grade_required": 8, "suggestions": ["voting", "election"]}
        ]
    },
    "recommendations": [
        {"fix": "Replace 'ratify' with 'approve' or 'agree to'"},
        {"fix": "Simplify sentence structure (current: 17 words avg)"}
    ]
}
```

**InceptBench Integration Point**: Add `accessibility` field to question evaluation output.

### 2. Vocabulary Database (5000+ words)
Word-to-grade mapping from Dolch, Fry, AWL word lists.

```python
from mirofish_simulator.accessibility import get_word_grade_level

get_word_grade_level("ratify")  # → 9
get_word_grade_level("vote")    # → 4
get_word_grade_level("dog")     # → 1
```

### 3. Prior Knowledge Requirements
What concepts a student needs to answer the question.

```python
result.prior_knowledge.required_concepts
# → ["Electoral College mechanics", "How presidents are elected", "State-level voting"]
```

## What MiroFish Does NOT Provide (Reliably)

### ❌ Accuracy Prediction
LLMs cannot constrain their knowledge through prompting. Agent-based simulation will show artificially high accuracy because the underlying model "knows" correct answers.

### ❌ IRT Parameters
We don't have calibration data. Any difficulty/discrimination values would be fabricated.

### ❌ Response Distribution Prediction
Can't reliably predict which wrong answers students would choose.

## Recommended Integration

### Option A: Accessibility as Evaluation Dimension

Add to existing InceptBench evaluators:

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

class InceptBenchEvaluator:
    def __init__(self):
        self.accessibility = AccessibilityAnalyzer()
        # ... other evaluators

    async def evaluate(self, question, target_grade=8):
        result = {
            # Existing dimensions
            "distractor_quality": await self.eval_distractors(question),
            "factual_accuracy": await self.eval_accuracy(question),

            # NEW: Accessibility dimension
            "accessibility": await self.accessibility.analyze(question, target_grade)
        }
        return result
```

### Option B: Standalone Accessibility Check

Separate endpoint for accessibility validation:

```python
# POST /api/inceptbench/accessibility
{
    "question": {...},
    "target_grade": 5
}

# Response
{
    "readable": false,
    "reading_level": 8.3,
    "target_grade": 5,
    "issues": [...],
    "recommendations": [...]
}
```

### Option C: CLI Flag

```bash
inceptbench evaluate question.json --check-accessibility --grade 5
```

## File Changes for Integration

### Backend

```python
# backend/app/api/inceptbench.py

@router.post("/accessibility")
async def check_accessibility(
    question: QuestionModel,
    target_grade: int = 8,
):
    from mirofish_simulator.accessibility import AccessibilityAnalyzer
    analyzer = AccessibilityAnalyzer()
    result = await analyzer.analyze(question.dict(), target_grade)
    return result.to_dict()
```

### Package Export

```python
# mirofish_simulator/__init__.py

from .accessibility import (
    AccessibilityAnalyzer,
    AccessibilityResult,
    flesch_kincaid_grade,
    get_word_grade_level,
)
```

## Value Proposition

| What InceptBench Has | What MiroFish Adds |
|---------------------|-------------------|
| LLM distractor analysis | Deterministic readability scores |
| Factual accuracy check | Vocabulary-to-grade mapping |
| Subject/topic tagging | Prior knowledge requirements |
| - | Actionable simplification recommendations |

MiroFish is NOT a replacement for InceptBench evaluation. It's a complementary tool for content accessibility validation.
