> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Governance, Safety & Accuracy

> Architectural guardrails, strict context grounding (RAG), deterministic caching, quality feedback loops, and circuit breaker governance in LearnWay AI.

# AI Governance, Safety & Accuracy

The LearnWay AI ecosystem powers conversational tutoring, skill assessments, and code grading. To ensure that AI outputs are **strictly grounded in curriculum facts, free of hallucinations, resilient to abuse, and ethically governed**, LearnWay enforces a multi-tier AI governance framework.

***

## AI Governance & Verification Pipeline

```mermaid theme={null}
graph TD
    UserReq["Learner Query / Assessment Prompt"] --> InputGuard["🛡️ Tier 1: Input Guarding & Sanitization<br/>• Profanity & Jailbreak Filter<br/>• Quota Check (5/lesson, 20/day)"]
    
    InputGuard --> CacheCheck{"⚡ Tier 2: Deterministic Cache Hit?<br/>(Redis 24h TTL)"}
    
    CacheCheck -->|Yes| FastReturn["Verified Deterministic Answer (< 50ms)"]
    
    CacheCheck -->|No| RAGEngine["📚 Tier 3: Strict Context Grounding (RAG)<br/>• Extract Active Slide Content<br/>• Inject Course Title & Difficulty Tier<br/>• Hard Grounding System Prompt Bounds"]
    
    RAGEngine --> LLMExec["🤖 Tier 4: Google Gemini Execution<br/>• 5-Second Timeout Race (Promise.race)<br/>• Output Token / Word Cap (<150 words)"]
    
    LLMExec --> CircuitCheck{"💥 Tier 5: Error / Latency Anomaly?"}
    
    CircuitCheck -->|Errors >= 5 in 60s| CircuitOpen["🔌 Circuit Breaker Opens (120s TTL)<br/>• Graceful Fallback Response"]
    CircuitCheck -->|Success| CacheStore["💾 Store in Redis & Log Audit Trail"]
    
    CacheStore --> FeedbackLoop["⭐ Tier 6: Quality Feedback & Auditing<br/>• User Thumbs Up / Down Tracking<br/>• Admin Quality Metrics by Course"]
```

***

## 1. Strict Context Grounding & Anti-Hallucination (RAG)

LearnWay prevents generative hallucinations by enforcing strict **Retrieval-Augmented Generation (RAG)** boundaries:

* **Curriculum Slide Injection (`buildContext`)**:
  * The service retrieves all active, approved lesson slides directly from PostgreSQL (`lessonRepo` + `slideRepo`).
  * Assembles a structured context header containing `Course Title`, `Lesson Title`, and `Difficulty Level (Beginner / Intermediate / Advanced)` alongside verbatim slide text and code snippets.
* **Hard Negative Constraints (`SYSTEM_PROMPT_TEMPLATE`)**:
  * The system prompt locks the model into the provided lesson content:
    > *"Stay strictly focused on the lesson content provided below."*\
    > *"Never answer questions unrelated to the lesson."*\
    > *"If asked something unrelated to the lesson, respond only with: 'That's outside this lesson — I can only help with what we're learning here.'"*
* **Difficulty Level Tuning**:
  * Ensures that explanations dynamically adjust terminology complexity to match the student's designated learning level.

***

## 2. Input Guardrails & Jailbreak Prevention

* **Pre-Execution Profanity & Prompt Injection Filter (`containsProfanity`)**:
  * Custom user questions are evaluated against security filters before invocation.
  * Rejects prompt injection attempts, toxic language, and malicious payload manipulation.
  * Audit logs rejected attempts with `status: 'rejected'` for security monitoring.

***

## 3. Deterministic Caching & Content Consistency

* **24-Hour Deterministic Cache (Redis TTL: 86,400s)**:
  * Standard prompt types (`EXPLAIN_SIMPLY`, `SUMMARIZE`, `EXAMPLE`, `KEY_TAKEAWAYS`) produce deterministic cache keys (`ai:cache:<lessonId>:<promptType>`).
  * **Educational Consistency**: Every student asking for an explanation on a specific lesson receives the exact same verified explanation.
* **Instant Cache Invalidation (`bustLessonCache`)**:
  * When curriculum creators update slide contents or code examples, the cache for that lesson is automatically purged to guarantee students always receive up-to-date guidance.

***

## 4. Quality Feedback Loop & Curriculum Auditing

```mermaid theme={null}
graph LR
    Student["Student UI"] -->|Thumbs Up / Down| FeedbackAPI["POST /api/v2/ai-tutor/feedback"]
    FeedbackAPI --> AuditStore[("AiLessonRequest Audit Log")]
    AuditStore --> AdminDashboard["Admin Quality Dashboard<br/>• Feedback Positive Rate %<br/>• Cache Hit Rate %<br/>• Avg Latency by Lesson"]
    AdminDashboard --> CurriculumRefine["Curriculum Designers Refine Confusing Slides"]
```

1. **Granular User Feedback (`submitFeedback`)**:
   * Students can submit positive or negative feedback on any AI-generated response.
2. **Curriculum-Level Auditing (`getCourseAnalytics`)**:
   * Generates metrics for `feedbackPositiveRate`, `avgLatencyMs`, `cacheHitRate`, and top asked prompt types across 24h, 7d, and 30d sliding windows.
   * Highlights confusing lessons with low feedback scores, prompting curriculum teams to improve lesson slide clarity.

***

## 5. Resilience, Quotas & Circuit Breaker Governance

| Governance Mechanism          | Configuration Parameter            | Threshold / Behavior                                                     |
| :---------------------------- | :--------------------------------- | :----------------------------------------------------------------------- |
| **Hard Execution Timeout**    | `AI_TUTOR_TIMEOUT_MS`              | **5,000 ms** (Enforced via `Promise.race`; avoids hanging client states) |
| **Circuit Breaker Threshold** | `AI_TUTOR_CIRCUIT_ERROR_THRESHOLD` | **5 errors within a 60-second window** opens circuit breaker             |
| **Circuit Breaker Reset**     | `AI_TUTOR_CIRCUIT_RESET_TTL`       | **120 seconds** cooldown before re-testing upstream Gemini health        |
| **Per-Lesson Quota**          | `AI_TUTOR_LESSON_LIMIT`            | **5 requests** per user per lesson                                       |
| **Daily Quota**               | `AI_TUTOR_DAILY_LIMIT`             | **20 requests** per user per day (Resets at midnight UTC)                |
| **Context Length Cap**        | `AI_TUTOR_MAX_CONTEXT_CHARS`       | **3,000 characters** (Prevents context window truncation)                |
| **Safe Fallback Response**    | `AI_FALLBACK_MESSAGE`              | Returns graceful user message during model outages or circuit trips      |