> ## 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 Assessments & Adaptive Personalization

> Architecture of AI-assisted onboarding assessments, multimodal capstone project evaluation, dynamic skill profiling, and personalized career roadmaps.

# AI Assessments & Adaptive Personalization

LearnWay replaces one-size-fits-all curricula with dynamic, AI-driven assessment and personalization pipelines. Generative models evaluate initial student aptitude, grade hands-on practical submissions, and construct custom career roadmaps.

```mermaid theme={null}
flowchart TD
    subgraph Phase1["1️⃣ Diagnostic Calibration & Placement"]
        OnboardingQuiz["Onboarding Assessment Answers"]
        CareerGoal["Target Career Goal (e.g. 'AI Engineer')"]
        SkillProfiler["Adaptive Skill Profiling Engine\n(Calibrates Baseline Aptitude)"]
    end

    subgraph Phase2["2️⃣ Dynamic Curriculum Synthesis"]
        CatalogDB[("Course Catalog & Prerequisite Graph")]
        RoadmapSynthesizer["Career Roadmap Generator\n(Foundation-First Calibration)"]
        PersonalizedRoadmap["Milestone Career Roadmap\n(Stages 1..N Tracks & Lessons)"]
    end

    subgraph Phase3["3️⃣ Practical Execution & Milestone Submission"]
        ActiveLearning["Bite-Sized Modular Lessons & Quizzes"]
        ProjectArtifacts["Capstone Deliverables\n(Code Repos, Architecture PDFs, UI Screens)"]
    end

    subgraph Phase4["4️⃣ Multimodal AI Evaluation & Feedback"]
        MultimodalEvaluator["AiAssessmentService (Gemini 1.5 Pro / Flash)\n• Code Quality & Security Evaluation\n• Rubric Scoring & Actionable Feedback"]
        GradingResult{"Score >= Passing Threshold?"}
    end

    subgraph Phase5["5️⃣ Accreditation & Continuous Feedback Loop"]
        KnowledgeGapEngine["Knowledge Gap Telemetry & Micro-Reviews\n(learnway-ai-service/ai-analytics)"]
        OnChainMinting["On-Chain Credential Minting\n(ERC-721 Badges / ERC-1155 Certificates)"]
        NextStageUnlock["Advance to Next Roadmap Stage & Update Employability Score"]
    end

    %% Phase 1 Connections
    OnboardingQuiz --> SkillProfiler
     OnboardingQuiz --> CareerGoal
    CareerGoal --> RoadmapSynthesizer
    SkillProfiler -->|Calibrated Level| RoadmapSynthesizer

    %% Phase 2 Connections
    CatalogDB --> RoadmapSynthesizer
    RoadmapSynthesizer --> PersonalizedRoadmap
    PersonalizedRoadmap --> ActiveLearning

    %% Phase 3 Connections
    ActiveLearning --> ProjectArtifacts
    ProjectArtifacts --> MultimodalEvaluator

    %% Phase 4 Connections
    MultimodalEvaluator --> GradingResult

    %% Phase 5 Closed Feedback Loop
    GradingResult -->|No - Needs Improvement| KnowledgeGapEngine
    KnowledgeGapEngine -->|Targeted Micro-Reviews| ActiveLearning

    GradingResult -->|Yes - Passed| OnChainMinting
    GradingResult -->|Yes - Passed| NextStageUnlock
    NextStageUnlock -->|Update Profile Telemetry| SkillProfiler
    NextStageUnlock -->|Advance Milestone| PersonalizedRoadmap
```

***

## 1. Adaptive Onboarding Assessment

When a new learner signs up, they complete a diagnostic onboarding evaluation:

1. **Diagnostic Domain Questions**: Evaluates baseline reasoning, programming fundamentals, AI literacy, and logic.
2. **Aptitude Calibration**: The AI engine processes answer patterns, response timing, and accuracy to determine the learner's foundational competence level (*Beginner*, *Intermediate*, or *Advanced*).
3. **Automated Path Placement**: Skips redundant introductory modules for advanced learners while directing novices to structured Foundation Learning Paths.

***

## 2. Multimodal Project & Capstone Evaluation (`AiAssessmentService`)

For practical capstone courses, learners submit real-world artifacts (code repositories, architecture diagrams, screenshots, or design documents).

### Multimodal Ingestion Pipeline

`AiAssessmentService` handles diverse deliverable types by preparing inline base64 and structured text parts for Google Gemini:

```typescript theme={null}
const INLINE_DATA_MIME_TYPES: Record<string, string> = {
  jpg: 'image/jpeg',
  jpeg: 'image/jpeg',
  png: 'image/png',
  webp: 'image/webp',
  gif: 'image/gif',
  pdf: 'application/pdf',
};
```

### Evaluation Rubric & JSON Output

The AI evaluates submissions against project criteria, returning a strictly formatted JSON response:

```json theme={null}
{
  "score": 88,
  "passed": true,
  "strengths": [
    "Clean separation of concerns in NestJS service layers",
    "Proper error handling with custom HTTP exceptions"
  ],
  "weaknesses": [
    "Missing input validation on nested DTO objects",
    "Database queries in controller methods instead of repositories"
  ],
  "recommendations": [
    "Apply class-validator decorators to all incoming payload properties",
    "Inject repositories into service providers to follow the repository pattern"
  ]
}
```

If the score meets the course passing threshold, the core backend automatically queues certificate minting on the supporting blockchain infrastructure (`Lisk L2`).

***

## 3. Dynamic Career Roadmap Generator

Learners can specify a targeted career ambition (such as *"Full Stack AI Engineer"*, *"Smart Contract Auditor"*, or *"Data Scientist"*).

### Synthesis Process:

1. **Catalog Querying**: Fetches all verified courses, tracks, and prerequisites currently published in LearnWay's catalog.
2. **Foundation Alignment**: Injects the **Foundation-First Rule**, guaranteeing that universal foundational courses precede advanced electives.
3. **Stage Breakdown**: Assembles a structured milestone roadmap where each stage references concrete courses in the catalog:

```json theme={null}
{
  "title": "Roadmap to Full Stack AI Engineer",
  "description": "Comprehensive milestone-driven path from foundational computing to production LLM integration.",
  "stages": [
    {
      "stage": 1,
      "title": "Foundational Computing & Logic",
      "courses": [
        "Intro to Modern Programming",
        "Data Structures & Algorithms"
      ],
      "skillsAcquired": ["TypeScript", "Algorithmic Thinking"]
    },
    {
      "stage": 2,
      "title": "AI & Machine Learning Essentials",
      "courses": [
        "Prompt Engineering & LLM Fundamentals",
        "Working with Gemini APIs"
      ],
      "skillsAcquired": ["Prompt Architecture", "RAG Pipelines", "Embeddings"]
    },
    {
      "stage": 3,
      "title": "Full Stack AI Application Engineering",
      "courses": [
        "NestJS Backend Architecture",
        "Building Mobile-First AI Applications"
      ],
      "skillsAcquired": [
        "Microservices",
        "Vector Databases",
        "Agentic Workflows"
      ]
    }
  ]
}
```

***

## 4. Continuous Knowledge Gap Detection

Throughout a learner's progression:

* **Quiz Battle Telemetry**: Tracks specific question categories where the learner frequently misses questions.
* **Micro-Recommendations**: Feeds knowledge gap metrics into `learnway-ai-service/ai-analytics` to suggest targeted micro-review slides before the next competitive battle or assessment.