Adaptive Learning Path System

An LLM-assisted adaptive learning prototype that converts learning goals or uploaded educational PDFs into prerequisite skill trees. The system supports expert review, node-aware tutoring, quiz generation, gap diagnosis, and bounded remedial graph repair.

This repository contains source code only. It does not include API keys, runtime cache, generated frontend builds, submitted report files, or deployment credentials.

What The System Does

The system is designed around a graph-based learning workflow:

PDF or learning goal
-> source-spine extraction / task routing
-> Architect skill-tree generation
-> Critic and deterministic validation
-> interactive expert workspace
-> Tutor / Quiz / gap diagnosis
-> remedial node insertion when a learner fails

The generated graph is not only a visualisation. It is the shared scaffold used for:

• prerequisite sequencing;
• recommended next node;
• node-aware Tutor context;
• node-specific quiz generation;
• learner progress state;
• personalization from an existing graph;
• remedial graph repair after quiz failure.

Main Features

• Upload PDF: builds a skill tree from lecture slides, topic PDFs, or structured textbook outlines.
• New Course: generates either a focused single-topic skill tree or a multi-stage learning pathway from a free-form learning goal.
• Quality modes: fast, balanced, and strict control generation cost, repair effort, and graph quality expectations.
• Balanced scope routing: routes bounded practical/concept goals to a faster single-topic tree, while broader career/course/competition goals use staged generation.
• Strict graph validation: uses shape checks and Critic review to reduce weak outputs such as long chains, disconnected nodes, noisy labels, or malformed graph structure.
• Expert workspace: supports graph inspection, node focusing, layout reset, node type editing, summary refresh, retrying failed stages, deleting courses, and manual node operations.
• Ask Tutor: answers questions using the selected node and surrounding graph context instead of acting as a stateless chatbot.
• Quiz and gap diagnosis: generates node-specific quizzes and proposes a likely missing prerequisite when the learner fails.
• Dynamic graph repair: inserts a remedial node before the failed concept so the learner can address a prerequisite gap.
• Personalize: adapts a current graph or selected subtree toward a new learner goal.
• Async jobs: long-running LLM tasks are handled through job polling so the frontend can show progress and avoid browser request timeouts.

Interface And Workflow Figures

Expert Workspace Overview

Selected Node Detail Panel

New Course Workflow

Upload PDF Workflow

Personalize Workflow

Ask Tutor, Quiz, Gap Diagnosis, And Repair

One-Page Button Reference

Repository Structure

.
  backend/
    main.py                    FastAPI app and API route definitions
    requirements.txt           Python dependencies
    .env.example               Provider/model configuration template
    services/
      learning_path_service.py Core generation, PDF routing, Tutor, Quiz, repair
      prompt_templates.py      Architect, Critic, Tutor, Quiz, repair prompts
      verification_service.py  Deterministic checks and Critic validation
      llm_client.py            Google/OpenAI-compatible provider wrapper
      model_config.py          Model lists and quality-mode configuration
      job_service.py           File-backed async job registry
      user_service.py          Prototype user/progress persistence
      gemini_service.py        Backward-compatible import facade
  frontend/
    src/
      App.jsx                  Main expert workspace and evaluation route state
      api.js                   API client, job polling, error normalization
      components/              React Flow tree, chat panel, quiz modal
      data/                    Fixed evaluation graph data
    package.json
  deploy/
    DEPLOY_ALIYUN.md           Optional deployment notes
    nginx/                     Nginx config example
    systemd/                   FastAPI service unit example
  docs/
    EXPERT_USER_GUIDE.md       Detailed expert UI operation guide
    EXPERT_UI_IMAGE_PROMPTS.md Prompts for generating annotated UI diagrams
    *.png                      Annotated interface and workflow guide figures

Quick Start For Local Testing

1. Backend

cd backend
pip install -r requirements.txt
copy .env.example .env
python main.py

Then edit backend/.env and add the LLM provider configuration. The backend runs on:

http://127.0.0.1:8000

2. Frontend

Open a second terminal:

cd frontend
npm install
npm run dev

The expert workspace runs on:

http://127.0.0.1:5173/expert

The frontend development server proxies /api/* requests to the local backend.

Environment Configuration

Create backend/.env from backend/.env.example.

Required variables:

LLM_PROVIDER=deepseek
LLM_API_KEY=your_provider_api_key_here
LLM_BASE_URL=https://api.deepseek.com
LLM_TIMEOUT_SECONDS=90
LLM_RETRY_COUNT=0
ARCHITECT_MODELS=deepseek-v4-flash,deepseek-v4-pro
TUTOR_MODELS=deepseek-v4-flash,deepseek-v4-pro
GRAPH_QUALITY_PASS_SCORE=80
GRAPH_REPAIR_ROUNDS=2
GRAPH_QUALITY_PROFILE=strict_v1

Supported provider styles:

• google: uses the Google Gemini SDK.
• deepseek, openai, or openai_compatible: uses an OpenAI-compatible /chat/completions endpoint.

Real API keys are not included in this repository. If the hosted version is being used for group evaluation, use the hosted URL shared separately by the project owner.

How To Test The Main Workflow

Use /expert and try the following:

1. Create or select a learner profile

   • Use the left sidebar profile selector or Create New Profile.

2. Generate a course from a goal

   • Open the New Course tab in the right AI Tutor panel.
   • Choose Balanced for normal testing.
   • Enter a learning goal such as How to buy Crystal Shrimp Dumpling.
   • Click Create.

3. Upload a PDF

   • Click Upload PDF in the top-right header.
   • Prefer lecture/topic PDFs with a clear title slide or embedded outline.
   • Structured textbooks should have a usable table of contents or outline.

4. Inspect the skill tree

   • Click nodes to inspect summaries, type, progress state, and actions.
   • Use Layered View / Show All and Reset Layout if the graph becomes hard to view.

5. Ask Tutor

   • Select a node.
   • Open Ask Tutor.
   • Ask a question about the selected concept. The answer should use graph context, not only the raw chat text.

6. Quiz and gap diagnosis

   • Open a selected node.
   • Click Quiz.
   • If the learner fails, the system can suggest a missing prerequisite and insert a remedial node.

7. Personalize

   • Select a tree or subtree.
   • Open Personalize.
   • Enter a goal describing how the current graph should be adapted.

See the full interface guide:

docs/EXPERT_USER_GUIDE.md

Generation Modes

Mode	Intended Use	Behaviour
fast	Quick draft / lightweight checks	Minimal repair and fastest model profile.
balanced	Main practical default	Scope-routed generation: focused single-topic trees for bounded goals, staged pathways for long-range goals.
strict	Higher quality review	More expensive model profile, stronger quality checks, and repair attempts.

For uploaded PDFs, mode support depends on the document route. Deterministic outline parsing may not need LLM generation, while flat lecture/topic PDFs may use compact deterministic grouping or LLM-assisted structuring.

API Overview

Important routes:

Route	Purpose
GET /	Backend health check.
POST /api/jobs/upload	Upload a PDF and start graph generation.
POST /api/jobs/generate-path	Start New Course generation from a learning goal.
POST /api/jobs/personalize-path	Start Personalize generation from an existing graph.
POST /api/jobs/regenerate-stage	Retry one failed/generated stage.
GET /api/jobs/{job_id}	Poll async job status and result.
POST /api/chat	Ask Tutor using selected node context.
POST /api/quiz	Generate quiz questions for a selected node.
POST /api/gap-analysis	Suggest a missing prerequisite after quiz failure.
POST /api/verify	Run graph validation / Critic logic.
GET /api/users	Load prototype learner profiles.
POST /api/progress	Save learner node progress.

Build And Verification

Backend syntax check:

$files = @('backend/main.py') + (Get-ChildItem backend/services -Filter *.py | ForEach-Object { $_.FullName })
python -m py_compile @files

Frontend production build:

cd frontend
npm run build

Known Non-Blocking Warnings

The following warnings may appear during local testing. They are expected and do not prevent the prototype from running:

• google.generativeai deprecation warning: the backend keeps compatibility with the older Gemini SDK while also supporting OpenAI-compatible providers through the provider wrapper. Migration to google.genai is future maintenance work.
• Vite chunk-size warning after npm run build: the frontend currently builds into one large application chunk. The build still completes successfully.
• npm audit dependency warnings after npm install: these come from third-party frontend dependencies in the Vite/React toolchain. They do not block local execution or prototype testing.

These warnings should not be interpreted as failed installation or failed execution unless the command exits with an error code.

Runtime Files Not Included

The following files are runtime state and should not be committed:

• backend/.env
• backend/users.json
• backend/processed_cache.json
• backend/debug_spine_output.txt
• backend/runtime/jobs/*.json
• frontend/dist/
• frontend/node_modules/
• __pycache__/
• local log files

Scope And Limitations

This is a prototype feasibility system, not a production learning platform.

Current limitations:

• Graph correctness still requires expert review for high-stakes learning use.
• LLM output can vary between runs and providers.
• Poorly structured PDFs may be rejected or produce weaker trees.
• The user/profile store is prototype-level JSON persistence, not production authentication or multi-user isolation.
• The Critic reduces obvious structural failures but does not prove educational correctness.