# 1. AI Tutor Configuration

User Type: **Super Administrator**
Source: *Mi Digital Academy - Education CRM Features Document*

---

## 1. AI Tutor Configuration

### 1.1 Question Limits per Subscription Plan
**What it does:** Configures the AI tutor question limits per subscription plan: the daily/weekly/monthly question caps, the cap enforcement behavior, and the overage handling.

**Sub-features:**
- Question caps per plan (daily, weekly, monthly)
- Cap enforcement behavior (hard stop, soft warning)
- Overage handling (block, prompt upgrade, grace allowance)
- Per-plan cap overrides (promotional, trial)
- Cap usage reporting per student
- Available on web
- Event logging (action performed)
- Audit logging of AI tutor question limits

**Super Admin User Journey:**
1. Super Admin opens AI Feature Configuration → AI Tutor → Question Limits.
2. Sets the question caps per subscription plan (daily, weekly, monthly).
3. Configures the cap enforcement behavior (hard stop or soft warning) and the overage handling.
4. Defines per-plan overrides for promotional or trial plans.
5. Saves; the limits apply to all AI tutor sessions.
6. Each configuration change is event-logged and audit-logged.

**Rules & Edge Cases:**
- A student at the cap is handled per the overage rule (block, prompt upgrade, or grace allowance); there is no silent overage.
- A plan change (upgrade/downgrade) applies the new plan's caps from the change point; usage is not retroactively recalculated.
- Cap usage is reported per student and is immutable once recorded.
- Configuration changes are audit-logged with the plan, the change, and the timestamp.

### 1.2 Subject-Specific AI Behavior
**What it does:** Configures the AI tutor's subject-specific behavior: the teaching approach per subject, the difficulty calibration, and the subject-specific response style.

**Sub-features:**
- Teaching approach per subject (step-by-step, Socratic, direct answer)
- Difficulty calibration per subject and grade band
- Subject-specific response style (formal, conversational)
- Subject-specific knowledge scope (curriculum boundaries)
- Subject enable/disable (AI tutor availability per subject)
- Available on web
- Event logging (action performed)
- Audit logging of subject-specific AI behavior

**Super Admin User Journey:**
1. Super Admin opens AI Feature Configuration → AI Tutor → Subject Behavior.
2. Sets the teaching approach per subject (step-by-step, Socratic, direct answer).
3. Calibrates the difficulty per subject and grade band.
4. Sets the subject-specific response style and the knowledge scope (curriculum boundaries).
5. Enables or disables the AI tutor per subject.
6. Saves; the behavior applies to AI tutor sessions in each subject.
7. Each configuration change is event-logged and audit-logged.

**Rules & Edge Cases:**
- A disabled subject shows no AI tutor access; questions in that subject are routed to human support or blocked per policy.
- The knowledge scope bounds the AI tutor's answers to the configured curriculum; out-of-scope questions are answered with a scope notice.
- A subject with no configured behavior falls back to the global default behavior.
- Configuration changes are audit-logged with the subject, the change, and the timestamp.

### 1.3 Multi-Language Response Settings
**What it does:** Configures the AI tutor's multi-language response settings: the supported languages, the default language, the language detection, and the mixed-language handling.

**Sub-features:**
- Supported language list
- Default response language (per student locale, per plan)
- Language detection (auto-detect from student input)
- Mixed-language handling (respond in the dominant language)
- Per-language quality thresholds (disable a language below threshold)
- Available on web
- Event logging (action performed)
- Audit logging of multi-language settings

**Super Admin User Journey:**
1. Super Admin opens AI Feature Configuration → AI Tutor → Languages.
2. Sets the supported language list and the default response language.
3. Configures the language detection (auto-detect from student input).
4. Sets the mixed-language handling (respond in the dominant language).
5. Defines the per-language quality thresholds.
6. Saves; the settings apply to AI tutor responses.
7. Each configuration change is event-logged and audit-logged.

**Rules & Edge Cases:**
- A language below its quality threshold is disabled for new responses; existing sessions finish in that language.
- An unsupported language in student input triggers a fallback to the default language with a notice.
- The default language is resolved per student locale, then per plan, then the global default.
- Configuration changes are audit-logged with the setting, the change, and the timestamp.

### 1.4 Response Quality Parameters
**What it does:** Configures the AI tutor response quality parameters: the accuracy target, the response length bounds, the citation/step-showing requirement, and the quality monitoring.

**Sub-features:**
- Accuracy target (minimum correctness threshold)
- Response length bounds (min/max length per response type)
- Step-showing requirement (show working for problem-solving)
- Citation requirement (reference curriculum sources where applicable)
- Quality monitoring (sampled responses reviewed for quality)
- Available on web
- Event logging (action performed)
- Audit logging of response quality parameters

**Super Admin User Journey:**
1. Super Admin opens AI Feature Configuration → AI Tutor → Response Quality.
2. Sets the accuracy target (minimum correctness threshold).
3. Configures the response length bounds and the step-showing requirement.
4. Sets the citation requirement (reference curriculum sources where applicable).
5. Enables quality monitoring (sampled responses reviewed for quality).
6. Saves; the parameters apply to AI tutor responses.
7. Each configuration change is event-logged and audit-logged.

**Rules & Edge Cases:**
- A response failing the accuracy target is flagged for review and, if confirmed incorrect, corrected and the incident logged.
- The step-showing requirement applies to problem-solving responses; factual responses are exempt.
- Quality monitoring samples are drawn per the configured rate; 100% sampling is allowed but rate-limited by volume.
- Configuration changes are audit-logged with the parameter, the change, and the timestamp.

### 1.5 Escalation to Human Tutor Rules
**What it does:** Defines the rules for escalating an AI tutor session to a human tutor: the escalation triggers, the escalation routing, and the handoff context.

**Sub-features:**
- Escalation triggers (repeated failure, student request, low-confidence answer)
- Escalation routing (subject-matched human tutor, queue)
- Handoff context (session summary, student level, unresolved question)
- Escalation availability window (human tutor hours)
- Escalation fallback (async ticket when no human available)
- Available on web
- Event logging (action performed)
- Audit logging of escalation rules

**Super Admin User Journey:**
1. Super Admin opens AI Feature Configuration → AI Tutor → Escalation.
2. Sets the escalation triggers (repeated failure, student request, low-confidence answer).
3. Configures the escalation routing (subject-matched human tutor, queue).
4. Defines the handoff context (session summary, student level, unresolved question).
5. Sets the availability window and the fallback (async ticket when no human available).
6. Saves; the rules apply to AI tutor sessions.
7. Each configuration change is event-logged and audit-logged.

**Rules & Edge Cases:**
- A student-requested escalation always succeeds (routed or ticketed); it is never silently dropped.
- A low-confidence answer triggers escalation only when the confidence is below the configured threshold.
- The handoff context is generated automatically from the session; the human tutor sees it before responding.
- Configuration changes are audit-logged with the rule, the change, and the timestamp.