deploy: edafea3

.dockerignore

@@ -0,0 +1,51 @@
+# Python caches
+**/__pycache__/
+**/*.py[cod]
+**/*.pyo
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Node
+node_modules/
+exam-app/
+!exam-app/src/data/exams.json
+!exam-app/src/data/questions.json
+
+# Env files (set secrets in Koyeb dashboard, not baked into image)
+.env
+*.env.local
+
+# Local wiki artifacts (rebuilt at runtime)
+math_wiki.db
+math_wiki.db-shm
+math_wiki.db-wal
+math_wiki.bm25.pkl
+math_wiki.faiss
+math_wiki.meta.pkl
+backend/math_wiki.db
+
+# Dev/test artifacts
+*.png
+*.pen
+test-results/
+tests/
+docs/
+core/
+validators/
+exam-app-plan.md
+response-*.json
+.gitnexus/
+.playwright-mcp/
+.claude/
+.kilo/
+playwright.config.js
+
+# Git
+.git/
+.gitignore

.env.example

@@ -0,0 +1,7 @@
+ANTHROPIC_BASE_URL=https://ai-router.locdo.tech
+ANTHROPIC_AUTH_TOKEN=your-auth-token-here
+ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4.6
+ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4.6
+ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4.5
+EMBEDDING_MODEL_NAME=BAAI/bge-m3
+EMBEDDING_DIM=1024

.github/workflows/admin-key-log.yml

@@ -0,0 +1,33 @@
+name: Admin Key Log (fallback)
+
+# Fallback scheduler — fires if cron-job.org misses a run.
+# Primary scheduler: cron-job.org (POST /admin/generate-key-log, X-Cron-Secret header)
+# This workflow is a safety net only; cron-job.org is preferred.
+#
+# Required GitHub repo secrets:
+#   HF_SPACE_URL  — e.g. https://your-space.hf.space
+#   CRON_SECRET   — same value as CRON_SECRET in HF Secrets (≥32 chars)
+#
+# Schedule: 20:05 UTC Sunday = 03:05 ICT Monday (5 min after cron-job.org fires at 20:00)
+# If cron-job.org already ran, the backend will just append a duplicate line — harmless.
+
+on:
+  schedule:
+    - cron: "5 20 * * 0"
+  workflow_dispatch:
+
+jobs:
+  trigger-key-log:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger key log generation
+        run: |
+          HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
+            -X POST "${{ secrets.HF_SPACE_URL }}/admin/generate-key-log" \
+            -H "X-Cron-Secret: ${{ secrets.CRON_SECRET }}" \
+            -H "Content-Type: application/json")
+          echo "Response status: $HTTP_STATUS"
+          if [ "$HTTP_STATUS" != "200" ]; then
+            echo "Key log generation failed with status $HTTP_STATUS"
+            exit 1
+          fi

.gitignore

@@ -0,0 +1,81 @@
+# Environment
+.env
+*.env.local
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Node
+node_modules/
+exam-app/dist/
+
+# Claude Code local settings (machine-specific)
+.claude/settings.local.json
+
+# GitNexus index (regenerated via `gitnexus analyze`)
+.gitnexus/
+
+# Ingestion state (local run progress, not source)
+exam-app/scripts/ingest/state.json
+backend/scripts/ingest/ingest_state.json
+
+# Cloudflare Pages / Wrangler local state
+.wrangler/
+
+# Misc
+*.pen
+.DS_Store
+Thumbs.db
+
+# Screenshots (all root-level PNGs are dev/test artifacts)
+*.png
+# Exception: question figure images are static assets shipped with the app
+!exam-app/public/images/questions/*.png
+
+# Math wiki local artifacts (regenerated by ingest pipeline)
+math_wiki.db
+math_wiki.db-shm
+math_wiki.db-wal
+math_wiki.bm25.pkl
+math_wiki.faiss
+math_wiki.meta.pkl
+backend/math_wiki.db
+
+# Crawl runtime state
+scripts/crawl_progress.json
+
+# Test results
+test-results/
+
+# Playwright MCP cache
+.playwright-mcp/
+
+# Local dev/agent artifacts
+.claude/
+docs/
+exam-app-plan.md
+
+# Kilo Code editor state
+.kilo/
+
+# Standalone agent framework (not integrated into the app)
+core/
+
+# Unused standalone validators (not imported by backend or exam-app)
+validators/
+
+# Empty local dev API response dumps
+response-*.json
+
+# Runtime caches
+scripts/.pauls_sentences_cache.json

AGENTS.md

@@ -0,0 +1,87 @@
+## Auth & Credit System
+
+### Auth-required endpoints
+All AI endpoints (`/analyze`, `/hint`, `/explain`, `/study-plan`) require a valid JWT in `Authorization: Bearer <token>`. The token is obtained from `POST /auth/google`.
+
+### Credit deduction per feature
+| Feature | Endpoint | Credits |
+|---|---|---|
+| Socratic hint | POST /hint | 1 |
+| Answer explanation | POST /explain | 1 |
+| Result analysis | POST /analyze | 3 |
+| Study plan | POST /study-plan | 5 |
+
+`/study-plan` also requires `subscription_tier` ∈ {student, complete} — returns 403 `tier_required` otherwise.
+
+### Getting the current admin key
+
+Admin keys rotate automatically (default: weekly). Get the current key from either:
+1. **HF Spaces** → Files tab → `/data/admin_keys.txt` → copy the latest line's key
+2. **Local fallback**: `python tools/gen_admin_key.py` (prompts for `ADMIN_MASTER_SECRET`)
+
+### Granting manual top-ups (admin)
+```
+POST /admin/users/{user_id}/credits
+X-Admin-Key: <current derived key from admin_keys.txt or gen_admin_key.py>
+{"amount": 500, "reason": "manual_topup_bank_transfer"}
+```
+
+### Activating subscriptions (admin)
+```
+POST /admin/users/{user_id}/subscription
+X-Admin-Key: <current derived key>
+{"tier": "student", "period": "monthly", "expires_at": "2026-06-15T00:00:00Z", "bonus_credits": 0}
+```
+
+### Suspending abusive accounts (admin)
+```
+POST /admin/users/{user_id}/suspend
+X-Admin-Key: <current derived key>
+{"reason": "credit_velocity abuse"}
+```
+
+The abuse detector (`backend/app/abuse_detector.py`) runs every 5 minutes and auto-suspends on HIGH-confidence signals (credit velocity, burst >100 req/10min). MEDIUM-confidence events are logged to `security_events` for manual review via `GET /admin/security-events`.
+
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **AI-Agent-App** (5942 symbols, 18107 relationships, 265 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/AI-Agent-App/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/AI-Agent-App/clusters` | All functional areas |
+| `gitnexus://repo/AI-Agent-App/processes` | All execution flows |
+| `gitnexus://repo/AI-Agent-App/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

CLAUDE.md

@@ -0,0 +1,271 @@
+# AI Agent App
+
+Zenith — AI-native adaptive learning system for Vietnamese students (FastAPI + Claude via ai-router proxy).
+
+## Stack
+
+- **Python** — FastAPI, pydantic-settings, tenacity, openai SDK (>=1.58.0)
+- **Runtime** — uvicorn
+- **AI** — Claude models via internal OpenAI-compatible proxy at `https://ai-router.locdo.tech`
+
+## Dev commands
+
+```bash
+# Run both backend + frontend together (preferred)
+npm install          # install concurrently (root, first time only)
+npm run dev          # starts backend :8000 and frontend :5173 concurrently
+
+# Backend only
+pip install -r requirements.txt
+PYTHONPATH=backend uvicorn app.main:app --reload   # http://localhost:8000
+python3 -m pytest backend/tests/        # run tests
+
+# Frontend only
+cd exam-app && npm install && npm run dev   # http://localhost:5173
+```
+
+## Project structure
+
+```
+backend/app/
+  config.py          # Settings (pydantic-settings), get_settings(); ALLOWED_ORIGINS for CORS
+  dependencies.py    # get_ai_client() singleton (AsyncOpenAI)
+  middleware.py      # RateLimitMiddleware — IP (20/min) + per-user (60/min) + rapid-fire hint detection
+  abuse_detector.py # Background loop (5 min) — credit velocity, burst, score anomaly, new-account checks
+  main.py            # FastAPI routes: /analyze /hint /explain /study-plan /health
+                     #   + /auth/google, /users/me, /users/me/profile, /users/me/credits/log
+                     #   + /admin/users/{id}/subscription|credits|suspend|unsuspend
+                     #   + GET /admin/security-events
+  agent/
+    core.py          # call_with_retry() — tenacity retry wrapper for all AI calls
+    memory.py        # compress_conversation() via Haiku
+    exam_analyzer.py # analyze_exam_result() — grade+province → location-aware school recs
+    hint_generator.py# generate_hint() — Socratic hints via Haiku
+    study_planner.py # generate_study_plan() — 4-week study plan with JSON fallback
+  tests/
+    test_ai_endpoints.py  # pytest tests covering AI endpoints (LLM mocked)
+
+exam-app/src/
+  api/
+    index.js         # Static data loaders (questions, exams, schools)
+    aiClient.js      # Axios client wrapping all backend endpoints; wrap() preserves structured errors
+  components/
+    AIInsights.jsx   # Renders AI analysis; handles 401/402/403 error codes + credit top-up CTA
+    AIErrorBoundary.jsx  # React error boundary wrapping AI sections
+    QuestionCard.jsx # Question renderer + hint (⚡1 credit) + explanation toggle (practice mode)
+    ProfileOnboarding.jsx # Modal: grade (required) + province (required) + school type + ToS gate
+    LowCreditBanner.jsx   # Sticky banner when credits_balance < 10; dismissible per session
+    Navbar.jsx       # ⚡ credits badge → /account; avatar/name → /account
+  pages/
+    Results.jsx      # Async AI analysis with grade+province in payload; "Tạo Kế Hoạch" button
+    StudyPlan.jsx    # /study-plan/:resultId — 4-week plan with localStorage checkbox progress
+    Account.jsx      # /account — profile, tier/credits, pricing table (monthly/annual toggle), credit log
+    ExamSelect.jsx   # Auth gate (1 guest trial), grade/tier filter, category lock for non-complete tiers
+  context/
+    ExamContext.jsx  # Exam state + hints: {} + SET_HINT action + useHints() hook
+    AuthContext.jsx  # user (all profile fields), login, logout, updateProfile()
+```
+
+## User profile fields (users table)
+
+| Field | Values | Effect |
+|---|---|---|
+| `grade` | '9','10','11','12' | ≤9 → grade10 exams only; 10-12 → thpt only |
+| `province` | 63 VN provinces | AI school recs localized to province |
+| `school_type` | 'chuyên','công lập','quốc tế' | Optional, informational |
+| `subscription_tier` | 'basic','student','complete' | Controls exam access + study-plan gate |
+| `subscription_period` | 'monthly','annual' | Annual shown with badge in Navbar/Account |
+| `credits_balance` | integer ≥0 | Deducted per AI call; 402 when exhausted |
+| `tos_accepted_at` | ISO timestamp | Required before any credit-deducting request |
+| `is_suspended` | 0/1 | 403 account_suspended → suspension modal |
+
+## AI credit costs
+
+| Endpoint | Credits |
+|---|---|
+| `/hint` | 1 |
+| `/explain` | 1 |
+| `/analyze` | 3 |
+| `/study-plan` | 5 (student/complete tier only) |
+
+## Admin endpoints (require X-Admin-Key: current derived key)
+
+Admin key rotates automatically (default: weekly). Get current key from `/data/admin_keys.txt` on HF Spaces or run `python tools/gen_admin_key.py`.
+
+- `POST /admin/users/{id}/subscription` — set tier/period/expiry + bonus credits
+- `POST /admin/users/{id}/credits` — grant top-up credits
+- `POST /admin/users/{id}/suspend` — suspend with reason
+- `POST /admin/users/{id}/unsuspend`
+- `GET /admin/security-events` — recent HIGH/MEDIUM events with user status
+- `POST /admin/generate-key-log` — (cron use only) derive + append current key to log; requires `X-Cron-Secret` header
+
+## AI router rules (CRITICAL)
+
+- **SDK**: `openai` (never `anthropic`)
+- **Base URL**: `https://ai-router.locdo.tech/v2` (set via `ANTHROPIC_BASE_URL` env var)
+- **Auth**: env var `ANTHROPIC_AUTH_TOKEN` — never hardcode
+- **Model names use dots**: `claude-sonnet-4.6`, `claude-opus-4.6`, `claude-haiku-4.5`
+- **Never hardcode model names** — use `settings.default_model` / `settings.opus_model` / `settings.haiku_model`
+- **Never create a new client per request** — use singleton `get_ai_client()` from `dependencies.py`
+
+## Model tiers
+
+| Property | Model | Use |
+|---|---|---|
+| `settings.default_model` | `claude-sonnet-4.6` | Main agent loop |
+| `settings.haiku_model` | `claude-haiku-4.5` | Cheap tasks: summarization, compression |
+| `settings.opus_model` | `claude-opus-4.6` | Complex reasoning |
+
+## Env vars
+
+**`backend/.env`** (copy from `backend/.env.example`, never commit)
+
+| Variable | Example value |
+|---|---|
+| `ANTHROPIC_BASE_URL` | `https://ai-router.locdo.tech` |
+| `ANTHROPIC_AUTH_TOKEN` | *(your token)* |
+| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `claude-opus-4.6` |
+| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `claude-sonnet-4.6` |
+| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `claude-haiku-4.5` |
+| `ALLOWED_ORIGINS` | `http://localhost:5173` |
+| `SQLITE_PATH` | `./math_wiki.db` (local) / `/data/app.db` (HF Spaces) |
+| `GOOGLE_CLIENT_ID` | *(Google OAuth client ID)* |
+| `JWT_SECRET` | *(≥32 chars, required)* |
+| `ADMIN_MASTER_SECRET` | *(≥32 chars — static master; effective key is HMAC-derived + time window)* |
+| `ADMIN_KEY_ROTATION_PERIOD` | `weekly` *(daily\|weekly\|monthly\|quarterly\|annual)* |
+| `ADMIN_KEY_LOG_PATH` | `./admin_keys.txt` (local) / `/data/admin_keys.txt` (HF Spaces) |
+| `ADMIN_KEY_LOG_ENABLED` | `true` |
+| `CRON_SECRET` | *(≥32 chars — authenticates POST /admin/generate-key-log from cron-job.org/GitHub Actions)* |
+
+**`exam-app/.env`** (copy from `exam-app/.env.example`, never commit)
+
+| Variable | Example value |
+|---|---|
+| `VITE_API_BASE_URL` | `http://localhost:8000` |
+
+## Key patterns
+
+**Error handling** — wrap all `client.chat.completions.create()` with `call_with_retry()` from `agent/core.py`. Catches `RateLimitError` (retry), `APIConnectionError`, `APIStatusError`.
+
+**Prefix caching** — static system prompt content first (e.g. `STATIC_EXAM_ANALYSIS_INSTRUCTIONS`); dynamic context (student name, score, weak topics) appended last.
+
+**Pricing** — `PRICE_TABLE` in `tools/registry.py` maps product type → VND/m². Default fallback: 1,600,000 VND/m².
+
+## Development workflow
+
+This project uses two collaborating tools for code intelligence and structured work:
+
+- **GitNexus MCP** — knowledge graph of 109 symbols and 162 relationships, indexed from the codebase. Use it to understand blast radius before editing, trace execution flows, and do safe renames.
+- **agent-skills plugin** — structured workflow skills (spec, plan, build, test, review, etc.) that map to common engineering tasks.
+
+### When to reach for each
+
+| Task | Use |
+|---|---|
+| "What calls `run_agent()`?" / "What breaks if I change this?" | GitNexus: `gitnexus_impact`, `gitnexus_context` |
+| "How does the tool loop work?" / "Find all entry points" | GitNexus: `gitnexus_query` |
+| Adding a new feature end-to-end | agent-skills: `/spec` → `/plan` → `/build` |
+| Fixing a bug with proof it's fixed | agent-skills: `/test` (Prove-It pattern) |
+| Pre-merge check | agent-skills: `/review` + GitNexus: `gitnexus_detect_changes` |
+| Renaming a symbol across files | GitNexus: `gitnexus_rename` |
+
+### GitNexus rules
+
+- **Before any coding task in `exam-app/` or `backend/`** — ALWAYS run `npx gitnexus analyze --embeddings` to refresh the index, then run the relevant GitNexus MCP tools (impact, context, query) before writing a single line of code.
+- **Before editing any symbol** — run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius. Stop and warn the user on HIGH or CRITICAL risk.
+- **Before committing** — run `gitnexus_detect_changes()` to verify only expected symbols were affected.
+- **Never rename with find-and-replace** — use `gitnexus_rename` which understands the call graph.
+
+### GitNexus skill files
+
+| Goal | Skill |
+|---|---|
+| Architecture exploration | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / impact analysis | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Bug tracing | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Refactoring / rename / extract | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Full tool + resource reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+
+### GitNexus index state
+
+Indexed as **AI-Agent-App** — re-index with `gitnexus analyze /mnt/d/AI-Agent-App --skip-git` after significant changes.
+
+### GitNexus MCP resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/AI-Agent-App/context` | Codebase overview, index freshness |
+| `gitnexus://repo/AI-Agent-App/processes` | All execution flows |
+
+<!-- gitnexus:start -->
+# GitNexus ��� Code Intelligence
+
+This project is indexed by GitNexus as **AI-Agent-App** (5942 symbols, 18107 relationships, 265 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/AI-Agent-App/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/AI-Agent-App/clusters` | All functional areas |
+| `gitnexus://repo/AI-Agent-App/processes` | All execution flows |
+| `gitnexus://repo/AI-Agent-App/process/{name}` | Step-by-step execution trace |
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->
+
+## Deploy commands
+
+### Hugging Face Space (backend) — orphan push required
+
+```bash
+git checkout master
+git checkout --orphan hf-deploy-new
+git add -A
+git commit -m "deploy: $(git log master --oneline -1 | cut -c1-7)"
+git branch -D hf-deploy
+git branch -m hf-deploy-new hf-deploy
+git push --force space hf-deploy:main
+git checkout master
+```
+
+**Never** use `git merge master` on hf-deploy — the repo history contains old binary files that HF rejects. The orphan commit has no parents, so none of that history is included.
+
+### Cloudflare Pages (frontend) — must use `--branch=main`
+
+```bash
+cd exam-app
+VITE_API_BASE_URL=https://minhtai-ai-agent-app.hf.space npm run build
+npx wrangler pages deploy dist --project-name exam-app --branch=main --commit-dirty=true
+```
+
+**Always** pass `--branch=main`. Without it, wrangler creates a **Preview** deployment (not Production), and `exam-app-ey0.pages.dev` keeps serving the old bundle. The production URL only aliases Production deployments.
+
+**Always** set `VITE_API_BASE_URL` explicitly. `exam-app/.env.local` (used for local dev) takes precedence over `exam-app/.env` in Vite's env loading order, so omitting the explicit override bakes `localhost:8000` into the production bundle.

Dockerfile

@@ -0,0 +1,30 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Fix root→appuser cache path mismatch; must be set before bake AND kept for CMD
+ENV HF_HOME=/app/.cache/huggingface
+
+# Bake BGE-M3 into the image; avoids cold-start download (~570 MB)
+RUN python -c "from FlagEmbedding import BGEM3FlagModel; BGEM3FlagModel('BAAI/bge-m3', use_fp16=False)"
+
+COPY backend/ backend/
+COPY scripts/ scripts/
+COPY exam-app/src/data/ exam-app/src/data/
+
+ENV PYTHONPATH=/app/backend:/app/scripts
+
+# HF Spaces requires a non-root user
+RUN useradd -m -u 1000 appuser && chown -R appuser /app
+USER appuser
+
+EXPOSE 7860
+
+CMD uvicorn app.main:app --host 0.0.0.0 --port 7860

README.md

@@ -0,0 +1,15 @@
+---
+title: AI Agent App
+emoji: 🤖
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+app_port: 7860
+---
+
+# AI Agent App
+
+Vietnamese aluminum/glass door sales chatbot + AI-powered exam backend.
+
+Built with FastAPI + Claude via ai-router proxy.

backend/.env.example

@@ -0,0 +1,23 @@
+ANTHROPIC_BASE_URL=https://ai-router.locdo.tech
+ANTHROPIC_AUTH_TOKEN=your_token_here
+ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4.6
+ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4.6
+ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4.5
+ALLOWED_ORIGINS=http://localhost:5173
+# SQLite database path. On HF Spaces use /data/app.db (persistent storage must be enabled).
+# For local dev override to e.g. ./math_wiki.db
+SQLITE_PATH=/data/app.db
+# Enable background wiki crawl on startup (local only; keep false on HF Spaces)
+CRAWL_AUTO_SEED_ENABLED=false
+# Wipe wiki_units and re-crawl from scratch; app self-disables this after one run
+CRAWL_FORCE_RESEED=false
+# Crawl only topics with zero wiki units (gap-fill); idempotent — safe to leave true
+CRAWL_GAP_FILL_ENABLED=false
+# Google OAuth 2.0 Client ID — create at console.cloud.google.com → Credentials → OAuth 2.0 Client IDs
+# Add Authorised JavaScript Origins: http://localhost:5173 and your HF Space URL
+GOOGLE_CLIENT_ID=your_google_client_id_here
+# JWT signing secret — generate with: python -c "import secrets; print(secrets.token_hex(32))"
+JWT_SECRET=your_jwt_secret_here
+# Static admin key sent in X-Admin-Key header for all admin endpoints.
+# Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+ADMIN_KEY=your_admin_key_here

backend/app/abuse_detector.py

@@ -0,0 +1,232 @@
+"""
+Background abuse detection loop — runs every 5 minutes, no external infrastructure needed.
+Launched in lifespan() via asyncio.ensure_future().
+"""
+import asyncio
+import json
+import logging
+
+logger = logging.getLogger(__name__)
+
+_INTERVAL = 300  # 5 minutes
+
+
+async def _log_event(pool, user_id, ip, event_type, confidence, detail):
+    try:
+        await pool.execute(
+            "INSERT INTO security_events (user_id, ip, event_type, confidence, detail) VALUES (?, ?, ?, ?, ?)",
+            user_id, ip, event_type, confidence, json.dumps(detail) if isinstance(detail, dict) else detail,
+        )
+    except Exception as exc:
+        logger.warning("abuse_detector: could not log event: %s", exc)
+
+
+async def _auto_suspend(pool, user_id, reason):
+    try:
+        await pool.execute(
+            "UPDATE users SET is_suspended = 1, suspension_reason = ? WHERE id = ?",
+            reason, user_id,
+        )
+        await _log_event(pool, user_id, None, "auto_suspend", "high", reason)
+        logger.warning("abuse_detector: AUTO-SUSPENDED user %s — %s", user_id, reason)
+    except Exception as exc:
+        logger.error("abuse_detector: failed to suspend user %s: %s", user_id, exc)
+
+
+async def _flag_for_review(pool, user_id, detail):
+    try:
+        await _log_event(pool, user_id, None, "flagged_for_review", "medium", detail)
+        logger.info("abuse_detector: flagged user %s for review — %s", user_id, detail)
+    except Exception as exc:
+        logger.error("abuse_detector: failed to flag user %s: %s", user_id, exc)
+
+
+async def _check_credit_velocity(pool):
+    """Credits 0→50+ in <1h after reset → HIGH confidence abuse."""
+    try:
+        rows = await pool.fetch(
+            """SELECT user_id, COUNT(*) as gains
+               FROM ai_credits_log
+               WHERE delta > 0
+                 AND reason NOT LIKE 'admin_%'
+                 AND reason NOT LIKE 'subscription_%'
+                 AND created_at > datetime('now', '-1 hour')
+               GROUP BY user_id HAVING gains >= 3"""
+        )
+        for row in rows:
+            await _auto_suspend(pool, row["user_id"], "credit_velocity: rapid credit gains detected")
+    except Exception as exc:
+        logger.warning("abuse_detector: credit_velocity check error: %s", exc)
+
+
+async def _check_burst_patterns(pool):
+    """More than 100 AI requests in a 10-min window → HIGH confidence."""
+    try:
+        rows = await pool.fetch(
+            """SELECT user_id, COUNT(*) as cnt
+               FROM ai_credits_log
+               WHERE created_at > datetime('now', '-10 minutes')
+               GROUP BY user_id HAVING cnt > 100"""
+        )
+        for row in rows:
+            await _auto_suspend(
+                pool, row["user_id"],
+                f"burst_pattern: {row['cnt']} AI requests in 10 minutes"
+            )
+    except Exception as exc:
+        logger.warning("abuse_detector: burst_patterns check error: %s", exc)
+
+
+async def _check_score_anomalies(pool):
+    """Score=10 on >3 exams in 30 min by same user → flag for review."""
+    try:
+        rows = await pool.fetch(
+            """SELECT user_id, COUNT(*) as cnt
+               FROM exam_results
+               WHERE score = 10 AND created_at > datetime('now', '-30 minutes')
+               GROUP BY user_id HAVING cnt > 3"""
+        )
+        for row in rows:
+            await _flag_for_review(
+                pool, row["user_id"],
+                f"score_anomaly: {row['cnt']} perfect-score exams in 30 minutes"
+            )
+    except Exception as exc:
+        logger.warning("abuse_detector: score_anomalies check error: %s", exc)
+
+
+async def _check_new_account_burst(pool):
+    """Account age <2h AND credits=0 (exhausted immediately) → flag for review."""
+    try:
+        rows = await pool.fetch(
+            """SELECT id FROM users
+               WHERE credits_balance = 0
+                 AND created_at > datetime('now', '-2 hours')
+                 AND is_suspended = 0"""
+        )
+        for row in rows:
+            await _flag_for_review(
+                pool, row["id"],
+                "new_account_burst: new account exhausted credits within 2 hours"
+            )
+    except Exception as exc:
+        logger.warning("abuse_detector: new_account_burst check error: %s", exc)
+
+
+async def _check_behavioral_anomalies(pool):
+    """Tab switches >10 or DevTools detected in a single day → behavior_anomaly event."""
+    try:
+        rows = await pool.fetch(
+            """SELECT user_id,
+                      SUM(CAST(json_extract(payload, '$.tab_switches') AS INTEGER)) AS total_tabs,
+                      MAX(CAST(json_extract(payload, '$.devtools_detected') AS INTEGER)) AS any_devtools
+               FROM exam_results
+               WHERE created_at > datetime('now', '-1 day')
+               GROUP BY user_id
+               HAVING total_tabs > 10 OR any_devtools = 1"""
+        )
+        for row in rows:
+            reason = f"behavior_anomaly: tab_switches={row['total_tabs']}, devtools={row['any_devtools']}"
+            await _log_event(pool, row["user_id"], None, "behavior_anomaly", "medium", reason)
+            # If user already has a HIGH event in the same window, auto-lock
+            high_events = await pool.fetchrow(
+                """SELECT COUNT(*) AS cnt FROM security_events
+                   WHERE user_id = ? AND confidence = 'high'
+                     AND created_at > datetime('now', '-1 day')""",
+                row["user_id"],
+            )
+            if high_events and high_events["cnt"] > 0:
+                await pool.execute(
+                    "UPDATE users SET is_locked = 1, lock_reason = ? WHERE id = ? AND is_locked = 0",
+                    f"auto-lock: {reason}", row["user_id"],
+                )
+                await _log_event(pool, row["user_id"], None, "auto_lock", "high", f"auto-lock: {reason}")
+                from app.dependencies import invalidate_account_cache
+                invalidate_account_cache(row["user_id"])
+    except Exception as exc:
+        logger.warning("abuse_detector: behavioral_anomalies check error: %s", exc)
+
+
+async def _auto_lock_on_high_confidence(pool):
+    """Auto-lock users with HIGH confidence abuse events if not already locked."""
+    try:
+        rows = await pool.fetch(
+            """SELECT DISTINCT user_id FROM security_events
+               WHERE confidence = 'high'
+                 AND event_type IN ('credit_velocity', 'burst_pattern', 'exam_anomaly')
+                 AND created_at > datetime('now', '-1 hour')"""
+        )
+        for row in rows:
+            result = await pool.execute(
+                "UPDATE users SET is_locked = 1, lock_reason = 'auto-lock: high-confidence abuse' WHERE id = ? AND is_locked = 0",
+                row["user_id"],
+            )
+            if result:
+                await _log_event(pool, row["user_id"], None, "auto_lock", "high", "auto-lock: high-confidence abuse event")
+                from app.dependencies import invalidate_account_cache
+                invalidate_account_cache(row["user_id"])
+    except Exception as exc:
+        logger.warning("abuse_detector: auto_lock check error: %s", exc)
+
+
+_DORMANT_DAYS = 365
+_DELETION_WARNING_DAYS = 30
+
+
+async def _mark_dormant_accounts(pool):
+    """Phase 1: mark basic-tier accounts inactive > _DORMANT_DAYS as pending deletion."""
+    try:
+        await pool.execute(
+            f"""UPDATE users
+               SET pending_deletion_at = datetime('now', '+{_DELETION_WARNING_DAYS} days')
+               WHERE subscription_tier = 'basic'
+                 AND is_suspended = 0 AND is_locked = 0 AND is_deactivated = 0
+                 AND pending_deletion_at IS NULL
+                 AND (last_seen_at IS NULL
+                      OR last_seen_at < datetime('now', '-{_DORMANT_DAYS} days'))
+            """
+        )
+    except Exception as exc:
+        logger.warning("abuse_detector: mark_dormant error: %s", exc)
+
+
+async def _deactivate_expired_pending(pool):
+    """Phase 2: deactivate accounts whose warning period has expired."""
+    try:
+        rows = await pool.fetch(
+            """SELECT id FROM users
+               WHERE pending_deletion_at IS NOT NULL
+                 AND pending_deletion_at < datetime('now')
+                 AND is_deactivated = 0"""
+        )
+        for row in rows:
+            await pool.execute(
+                "UPDATE users SET is_deactivated = 1 WHERE id = ?",
+                row["id"],
+            )
+            await _log_event(pool, row["id"], None, "auto_deactivated", "low",
+                             f"dormant account — no login for {_DORMANT_DAYS} days")
+            logger.info("abuse_detector: deactivated dormant account %s", row["id"])
+    except Exception as exc:
+        logger.warning("abuse_detector: deactivate_expired_pending error: %s", exc)
+
+
+async def _run_abuse_detector(pool):
+    """Main detection loop — runs every 5 minutes."""
+    logger.info("abuse_detector: starting background loop (interval=%ds)", _INTERVAL)
+    while True:
+        try:
+            await asyncio.sleep(_INTERVAL)
+            await _check_credit_velocity(pool)
+            await _check_burst_patterns(pool)
+            await _check_score_anomalies(pool)
+            await _check_new_account_burst(pool)
+            await _check_behavioral_anomalies(pool)
+            await _auto_lock_on_high_confidence(pool)
+            await _mark_dormant_accounts(pool)
+            await _deactivate_expired_pending(pool)
+        except asyncio.CancelledError:
+            logger.info("abuse_detector: loop cancelled, shutting down")
+            break
+        except Exception as exc:
+            logger.error("abuse_detector: unhandled error in loop: %s", exc)

backend/app/admin_auth.py

@@ -0,0 +1,67 @@
+import hmac
+import hashlib
+import datetime
+
+
+def get_window_label(period: str, offset: int = 0) -> str:
+    today = datetime.date.today()
+    if period == "daily":
+        return (today - datetime.timedelta(days=offset)).strftime("%Y-%m-%d")
+    elif period == "weekly":
+        return (today - datetime.timedelta(weeks=offset)).strftime("%Y-W%W")
+    elif period == "monthly":
+        year, month = today.year, today.month
+        month -= offset
+        while month <= 0:
+            month += 12
+            year -= 1
+        return f"{year}-{month:02d}"
+    elif period == "quarterly":
+        q = ((today.month - 1) // 3) + 1
+        year = today.year
+        q -= offset
+        while q <= 0:
+            q += 4
+            year -= 1
+        return f"{year}-Q{q}"
+    elif period == "annual":
+        return str(today.year - offset)
+    return (today - datetime.timedelta(weeks=offset)).strftime("%Y-W%W")
+
+
+def get_expiry_date(period: str) -> str:
+    today = datetime.date.today()
+    if period == "daily":
+        return (today + datetime.timedelta(days=1)).strftime("%Y-%m-%d")
+    elif period == "weekly":
+        days_until_next = (7 - today.weekday()) % 7 or 7
+        return (today + datetime.timedelta(days=days_until_next)).strftime("%Y-%m-%d")
+    elif period == "monthly":
+        if today.month == 12:
+            return f"{today.year + 1}-01-01"
+        return f"{today.year}-{today.month + 1:02d}-01"
+    elif period == "quarterly":
+        q = ((today.month - 1) // 3) + 1
+        next_q_month = q * 3 + 1
+        if next_q_month > 12:
+            return f"{today.year + 1}-01-01"
+        return f"{today.year}-{next_q_month:02d}-01"
+    elif period == "annual":
+        return f"{today.year + 1}-01-01"
+    days_until_next = (7 - today.weekday()) % 7 or 7
+    return (today + datetime.timedelta(days=days_until_next)).strftime("%Y-%m-%d")
+
+
+def derive_key(master: str, label: str) -> str:
+    return hmac.new(master.encode(), label.encode(), hashlib.sha256).hexdigest()
+
+
+def validate_admin_key(provided: str, master: str, period: str) -> bool:
+    if not master or not provided:
+        return False
+    current = derive_key(master, get_window_label(period, offset=0))
+    previous = derive_key(master, get_window_label(period, offset=1))
+    return (
+        hmac.compare_digest(provided.encode(), current.encode()) or
+        hmac.compare_digest(provided.encode(), previous.encode())
+    )

backend/app/agent/core.py

@@ -0,0 +1,7 @@
+from openai import AsyncOpenAI
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+
+@retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
+async def call_with_retry(client: AsyncOpenAI, **kwargs):
+    return await client.chat.completions.create(**kwargs)

backend/app/agent/exam_analyzer.py

@@ -0,0 +1,444 @@
+import json
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+
+THPT_ANALYSIS_CONTEXT = """
+Khi phân tích kết quả thi THPT:
+- Đề cập đến phân phối điểm chuẩn vào đại học theo tỉnh thành
+- Nhấn mạnh rằng 8.0+ thường cần thiết cho trường top
+- Chỉ ra xu hướng đề thi theo năm (khó hơn ở phần hình học không gian và tích phân)
+- Ưu tiên gợi ý trường phù hợp với điểm thực tế, không chỉ trường mơ ước
+"""
+
+STATIC_EXAM_ANALYSIS_INSTRUCTIONS = THPT_ANALYSIS_CONTEXT + """Bạn là chuyên gia phân tích kết quả học tập cho học sinh ôn thi Toán.
+Phân tích kết quả thi, các câu trả lời đúng/sai cụ thể, và gợi ý trường phù hợp dựa trên điểm số.
+Trả lời bằng tiếng Việt. Luôn trả về JSON hợp lệ theo đúng định dạng yêu cầu, không có text ngoài JSON."""
+
+# Per-province difficulty data (mirrors provincialData.js)
+# topic_weights: approximate % share of each topic in recent provincial grade-9 math exams.
+# Derived from analysis of 2021–2024 provincial exam papers. Topics with higher % are
+# higher priority in Recovery Path focus area selection.
+_PROVINCE_DATA = {
+    'Hà Nội': {
+        'difficulty': 4, 'typical_cutoff': 8.0, 'top_schools_cutoff': 9.2,
+        'topic_weights': {'calculus': 18, 'functions': 15, 'logarithm': 12, 'algebra': 14, 'geometry': 12, 'combinatorics': 10, 'hệ phương trình': 8, 'statistics': 6, 'sequences': 5},
+    },
+    'TP.HCM': {
+        'difficulty': 4, 'typical_cutoff': 7.8, 'top_schools_cutoff': 9.0,
+        'topic_weights': {'calculus': 16, 'functions': 15, 'algebra': 15, 'geometry': 13, 'logarithm': 10, 'combinatorics': 10, 'hệ phương trình': 8, 'statistics': 7, 'trigonometry': 6},
+    },
+    'Đà Nẵng': {
+        'difficulty': 3, 'typical_cutoff': 7.2, 'top_schools_cutoff': 8.5,
+        'topic_weights': {'algebra': 20, 'geometry': 18, 'functions': 13, 'calculus': 10, 'hệ phương trình': 10, 'statistics': 9, 'number_theory': 8, 'logarithm': 7, 'combinatorics': 5},
+    },
+    'Hải Phòng': {
+        'difficulty': 3, 'typical_cutoff': 7.0, 'top_schools_cutoff': 8.2,
+        'topic_weights': {'algebra': 20, 'geometry': 18, 'hệ phương trình': 12, 'functions': 12, 'statistics': 9, 'number_theory': 9, 'calculus': 8, 'logarithm': 7, 'combinatorics': 5},
+    },
+    'Cần Thơ': {
+        'difficulty': 3, 'typical_cutoff': 6.8, 'top_schools_cutoff': 8.0,
+        'topic_weights': {'algebra': 22, 'geometry': 18, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 10, 'statistics': 9, 'number_theory': 8, 'calculus': 6, 'căn thức': 5},
+    },
+    'Bình Dương': {
+        'difficulty': 3, 'typical_cutoff': 7.0, 'top_schools_cutoff': 8.2,
+        'topic_weights': {'algebra': 20, 'geometry': 18, 'hệ phương trình': 12, 'functions': 12, 'statistics': 9, 'number_theory': 9, 'calculus': 8, 'logarithm': 7, 'combinatorics': 5},
+    },
+    'Đồng Nai': {
+        'difficulty': 3, 'typical_cutoff': 6.8, 'top_schools_cutoff': 8.0,
+        'topic_weights': {'algebra': 22, 'geometry': 18, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 10, 'statistics': 9, 'number_theory': 8, 'calculus': 6, 'căn thức': 5},
+    },
+    'Khánh Hòa': {
+        'difficulty': 3, 'typical_cutoff': 6.8, 'top_schools_cutoff': 7.8,
+        'topic_weights': {'algebra': 22, 'geometry': 18, 'hệ phương trình': 11, 'arithmetic': 10, 'functions': 10, 'statistics': 9, 'number_theory': 8, 'calculus': 7, 'căn thức': 5},
+    },
+    'Nghệ An': {
+        'difficulty': 3, 'typical_cutoff': 6.6, 'top_schools_cutoff': 7.8,
+        'topic_weights': {'algebra': 22, 'geometry': 19, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 10, 'statistics': 8, 'number_theory': 8, 'calculus': 6, 'căn thức': 5},
+    },
+    'Thanh Hóa': {
+        'difficulty': 2, 'typical_cutoff': 6.4, 'top_schools_cutoff': 7.5,
+        'topic_weights': {'algebra': 25, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Hà Tĩnh': {
+        'difficulty': 3, 'typical_cutoff': 6.8, 'top_schools_cutoff': 7.8,
+        'topic_weights': {'algebra': 22, 'geometry': 18, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 10, 'statistics': 9, 'number_theory': 8, 'calculus': 6, 'căn thức': 5},
+    },
+    'Bắc Ninh': {
+        'difficulty': 3, 'typical_cutoff': 7.0, 'top_schools_cutoff': 8.2,
+        'topic_weights': {'algebra': 20, 'geometry': 18, 'hệ phương trình': 12, 'functions': 12, 'statistics': 9, 'number_theory': 9, 'calculus': 8, 'logarithm': 7, 'combinatorics': 5},
+    },
+    'Vĩnh Phúc': {
+        'difficulty': 3, 'typical_cutoff': 6.8, 'top_schools_cutoff': 7.8,
+        'topic_weights': {'algebra': 21, 'geometry': 18, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 10, 'statistics': 9, 'number_theory': 8, 'calculus': 7, 'căn thức': 5},
+    },
+    'Hà Giang': {
+        'difficulty': 1, 'typical_cutoff': 5.8, 'top_schools_cutoff': 6.8,
+        'topic_weights': {'algebra': 30, 'geometry': 25, 'arithmetic': 15, 'hệ phương trình': 10, 'statistics': 8, 'functions': 7, 'number_theory': 5},
+    },
+    'Điện Biên': {
+        'difficulty': 1, 'typical_cutoff': 5.6, 'top_schools_cutoff': 6.6,
+        'topic_weights': {'algebra': 32, 'geometry': 26, 'arithmetic': 16, 'hệ phương trình': 10, 'statistics': 8, 'functions': 5, 'number_theory': 3},
+    },
+    'Lai Châu': {
+        'difficulty': 1, 'typical_cutoff': 5.6, 'top_schools_cutoff': 6.6,
+        'topic_weights': {'algebra': 32, 'geometry': 26, 'arithmetic': 16, 'hệ phương trình': 10, 'statistics': 8, 'functions': 5, 'number_theory': 3},
+    },
+    'Sơn La': {
+        'difficulty': 1, 'typical_cutoff': 5.8, 'top_schools_cutoff': 6.8,
+        'topic_weights': {'algebra': 30, 'geometry': 25, 'arithmetic': 15, 'hệ phương trình': 10, 'statistics': 8, 'functions': 7, 'number_theory': 5},
+    },
+    'Cà Mau': {
+        'difficulty': 1, 'typical_cutoff': 5.8, 'top_schools_cutoff': 6.8,
+        'topic_weights': {'algebra': 30, 'geometry': 25, 'arithmetic': 15, 'hệ phương trình': 10, 'statistics': 8, 'functions': 7, 'number_theory': 5},
+    },
+    'Kiên Giang': {
+        'difficulty': 2, 'typical_cutoff': 6.2, 'top_schools_cutoff': 7.2,
+        'topic_weights': {'algebra': 25, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Bà Rịa - Vũng Tàu': {
+        'difficulty': 3, 'typical_cutoff': 7.0, 'top_schools_cutoff': 8.0,
+        'topic_weights': {'algebra': 20, 'geometry': 18, 'hệ phương trình': 12, 'functions': 12, 'statistics': 9, 'number_theory': 9, 'calculus': 8, 'logarithm': 7, 'combinatorics': 5},
+    },
+    # ── Difficulty-3 provinces (Khá) ──────────────────────────────────────────
+    'Thừa Thiên - Huế': {
+        'difficulty': 3, 'typical_cutoff': 6.8, 'top_schools_cutoff': 8.0,
+        'topic_weights': {'algebra': 20, 'geometry': 18, 'functions': 13, 'calculus': 10, 'hệ phương trình': 10, 'statistics': 9, 'number_theory': 9, 'logarithm': 7, 'combinatorics': 4},
+    },
+    'Quảng Ninh': {
+        'difficulty': 3, 'typical_cutoff': 7.0, 'top_schools_cutoff': 8.2,
+        'topic_weights': {'algebra': 20, 'geometry': 18, 'functions': 12, 'hệ phương trình': 12, 'statistics': 9, 'number_theory': 9, 'calculus': 8, 'logarithm': 7, 'combinatorics': 5},
+    },
+    'Nam Định': {
+        'difficulty': 3, 'typical_cutoff': 6.8, 'top_schools_cutoff': 7.8,
+        'topic_weights': {'algebra': 21, 'geometry': 18, 'hệ phương trình': 12, 'functions': 12, 'statistics': 9, 'number_theory': 9, 'calculus': 8, 'logarithm': 6, 'combinatorics': 5},
+    },
+    'Ninh Bình': {
+        'difficulty': 3, 'typical_cutoff': 6.6, 'top_schools_cutoff': 7.8,
+        'topic_weights': {'algebra': 21, 'geometry': 18, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 11, 'statistics': 9, 'number_theory': 8, 'calculus': 7, 'căn thức': 4},
+    },
+    'Hải Dương': {
+        'difficulty': 3, 'typical_cutoff': 6.8, 'top_schools_cutoff': 7.8,
+        'topic_weights': {'algebra': 20, 'geometry': 18, 'hệ phương trình': 12, 'functions': 12, 'statistics': 9, 'number_theory': 9, 'calculus': 8, 'logarithm': 7, 'combinatorics': 5},
+    },
+    'Hưng Yên': {
+        'difficulty': 3, 'typical_cutoff': 7.0, 'top_schools_cutoff': 8.0,
+        'topic_weights': {'algebra': 20, 'geometry': 18, 'hệ phương trình': 12, 'functions': 12, 'statistics': 9, 'number_theory': 9, 'calculus': 8, 'logarithm': 7, 'combinatorics': 5},
+    },
+    'Hà Nam': {
+        'difficulty': 3, 'typical_cutoff': 6.6, 'top_schools_cutoff': 7.6,
+        'topic_weights': {'algebra': 21, 'geometry': 18, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 11, 'statistics': 9, 'number_theory': 8, 'calculus': 7, 'căn thức': 4},
+    },
+    'Thái Bình': {
+        'difficulty': 3, 'typical_cutoff': 6.8, 'top_schools_cutoff': 7.8,
+        'topic_weights': {'algebra': 21, 'geometry': 18, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 11, 'statistics': 9, 'number_theory': 8, 'calculus': 7, 'căn thức': 4},
+    },
+    'Lâm Đồng': {
+        'difficulty': 3, 'typical_cutoff': 6.8, 'top_schools_cutoff': 7.8,
+        'topic_weights': {'algebra': 20, 'geometry': 18, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 11, 'statistics': 9, 'number_theory': 8, 'calculus': 7, 'căn thức': 5},
+    },
+    'Thái Nguyên': {
+        'difficulty': 3, 'typical_cutoff': 6.8, 'top_schools_cutoff': 7.8,
+        'topic_weights': {'algebra': 20, 'geometry': 18, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 11, 'statistics': 9, 'number_theory': 8, 'calculus': 7, 'căn thức': 5},
+    },
+    'Bình Định': {
+        'difficulty': 3, 'typical_cutoff': 6.8, 'top_schools_cutoff': 7.8,
+        'topic_weights': {'algebra': 21, 'geometry': 18, 'hệ phương trình': 11, 'arithmetic': 10, 'functions': 11, 'statistics': 9, 'number_theory': 8, 'calculus': 7, 'căn thức': 5},
+    },
+    'Quảng Nam': {
+        'difficulty': 3, 'typical_cutoff': 6.6, 'top_schools_cutoff': 7.6,
+        'topic_weights': {'algebra': 22, 'geometry': 18, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 10, 'statistics': 9, 'number_theory': 8, 'calculus': 6, 'căn thức': 5},
+    },
+    'Phú Thọ': {
+        'difficulty': 3, 'typical_cutoff': 6.8, 'top_schools_cutoff': 7.8,
+        'topic_weights': {'algebra': 20, 'geometry': 18, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 11, 'statistics': 9, 'number_theory': 8, 'calculus': 7, 'căn thức': 5},
+    },
+    'Bắc Giang': {
+        'difficulty': 3, 'typical_cutoff': 6.6, 'top_schools_cutoff': 7.6,
+        'topic_weights': {'algebra': 21, 'geometry': 18, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 11, 'statistics': 9, 'number_theory': 8, 'calculus': 7, 'căn thức': 4},
+    },
+    'Quảng Bình': {
+        'difficulty': 3, 'typical_cutoff': 6.6, 'top_schools_cutoff': 7.6,
+        'topic_weights': {'algebra': 22, 'geometry': 18, 'hệ phương trình': 12, 'arithmetic': 10, 'functions': 10, 'statistics': 9, 'number_theory': 8, 'calculus': 6, 'căn thức': 5},
+    },
+    # ── Difficulty-2 provinces (Trung bình) ───────────────────────────────────
+    'An Giang': {
+        'difficulty': 2, 'typical_cutoff': 6.2, 'top_schools_cutoff': 7.2,
+        'topic_weights': {'algebra': 25, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Bạc Liêu': {
+        'difficulty': 2, 'typical_cutoff': 6.0, 'top_schools_cutoff': 7.0,
+        'topic_weights': {'algebra': 26, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 9, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Bến Tre': {
+        'difficulty': 2, 'typical_cutoff': 6.2, 'top_schools_cutoff': 7.2,
+        'topic_weights': {'algebra': 25, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Bình Phước': {
+        'difficulty': 2, 'typical_cutoff': 6.2, 'top_schools_cutoff': 7.2,
+        'topic_weights': {'algebra': 25, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Bình Thuận': {
+        'difficulty': 2, 'typical_cutoff': 6.4, 'top_schools_cutoff': 7.4,
+        'topic_weights': {'algebra': 25, 'geometry': 21, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 8, 'căn thức': 5},
+    },
+    'Đắk Lắk': {
+        'difficulty': 2, 'typical_cutoff': 6.2, 'top_schools_cutoff': 7.2,
+        'topic_weights': {'algebra': 25, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Đắk Nông': {
+        'difficulty': 2, 'typical_cutoff': 6.0, 'top_schools_cutoff': 7.0,
+        'topic_weights': {'algebra': 26, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 9, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Đồng Tháp': {
+        'difficulty': 2, 'typical_cutoff': 6.2, 'top_schools_cutoff': 7.2,
+        'topic_weights': {'algebra': 25, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Gia Lai': {
+        'difficulty': 2, 'typical_cutoff': 6.0, 'top_schools_cutoff': 7.0,
+        'topic_weights': {'algebra': 26, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 9, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Hậu Giang': {
+        'difficulty': 2, 'typical_cutoff': 6.0, 'top_schools_cutoff': 7.0,
+        'topic_weights': {'algebra': 26, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 9, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Hòa Bình': {
+        'difficulty': 2, 'typical_cutoff': 6.0, 'top_schools_cutoff': 7.0,
+        'topic_weights': {'algebra': 26, 'geometry': 23, 'hệ phương trình': 11, 'arithmetic': 12, 'functions': 9, 'statistics': 8, 'number_theory': 6, 'căn thức': 5},
+    },
+    'Kon Tum': {
+        'difficulty': 2, 'typical_cutoff': 5.8, 'top_schools_cutoff': 6.8,
+        'topic_weights': {'algebra': 27, 'geometry': 23, 'arithmetic': 13, 'hệ phương trình': 11, 'statistics': 8, 'functions': 8, 'number_theory': 6, 'căn thức': 4},
+    },
+    'Lạng Sơn': {
+        'difficulty': 2, 'typical_cutoff': 6.0, 'top_schools_cutoff': 7.0,
+        'topic_weights': {'algebra': 26, 'geometry': 23, 'hệ phương trình': 11, 'arithmetic': 12, 'functions': 9, 'statistics': 8, 'number_theory': 6, 'căn thức': 5},
+    },
+    'Lào Cai': {
+        'difficulty': 2, 'typical_cutoff': 6.2, 'top_schools_cutoff': 7.2,
+        'topic_weights': {'algebra': 25, 'geometry': 23, 'hệ phương trình': 11, 'arithmetic': 12, 'functions': 9, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Long An': {
+        'difficulty': 2, 'typical_cutoff': 6.4, 'top_schools_cutoff': 7.4,
+        'topic_weights': {'algebra': 25, 'geometry': 21, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 8, 'căn thức': 5},
+    },
+    'Ninh Thuận': {
+        'difficulty': 2, 'typical_cutoff': 6.2, 'top_schools_cutoff': 7.2,
+        'topic_weights': {'algebra': 25, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Phú Yên': {
+        'difficulty': 2, 'typical_cutoff': 6.2, 'top_schools_cutoff': 7.2,
+        'topic_weights': {'algebra': 25, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Quảng Ngãi': {
+        'difficulty': 2, 'typical_cutoff': 6.2, 'top_schools_cutoff': 7.2,
+        'topic_weights': {'algebra': 25, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Quảng Trị': {
+        'difficulty': 2, 'typical_cutoff': 6.2, 'top_schools_cutoff': 7.2,
+        'topic_weights': {'algebra': 25, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Sóc Trăng': {
+        'difficulty': 2, 'typical_cutoff': 6.0, 'top_schools_cutoff': 7.0,
+        'topic_weights': {'algebra': 26, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 9, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Tây Ninh': {
+        'difficulty': 2, 'typical_cutoff': 6.4, 'top_schools_cutoff': 7.4,
+        'topic_weights': {'algebra': 25, 'geometry': 21, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 8, 'căn thức': 5},
+    },
+    'Tiền Giang': {
+        'difficulty': 2, 'typical_cutoff': 6.2, 'top_schools_cutoff': 7.2,
+        'topic_weights': {'algebra': 25, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Tuyên Quang': {
+        'difficulty': 2, 'typical_cutoff': 5.8, 'top_schools_cutoff': 6.8,
+        'topic_weights': {'algebra': 27, 'geometry': 23, 'arithmetic': 13, 'hệ phương trình': 11, 'statistics': 8, 'functions': 8, 'number_theory': 5, 'căn thức': 5},
+    },
+    'Vĩnh Long': {
+        'difficulty': 2, 'typical_cutoff': 6.2, 'top_schools_cutoff': 7.2,
+        'topic_weights': {'algebra': 25, 'geometry': 22, 'hệ phương trình': 12, 'arithmetic': 11, 'functions': 10, 'statistics': 8, 'number_theory': 7, 'căn thức': 5},
+    },
+    'Yên Bái': {
+        'difficulty': 2, 'typical_cutoff': 5.8, 'top_schools_cutoff': 6.8,
+        'topic_weights': {'algebra': 27, 'geometry': 23, 'arithmetic': 14, 'hệ phương trình': 11, 'statistics': 8, 'functions': 7, 'number_theory': 5, 'căn thức': 5},
+    },
+    # ── Difficulty-1 provinces (Dễ / vùng cao) ───────────────────────────────
+    'Bắc Kạn': {
+        'difficulty': 1, 'typical_cutoff': 5.8, 'top_schools_cutoff': 6.8,
+        'topic_weights': {'algebra': 30, 'geometry': 25, 'arithmetic': 15, 'hệ phương trình': 10, 'statistics': 8, 'functions': 7, 'number_theory': 5},
+    },
+    'Cao Bằng': {
+        'difficulty': 1, 'typical_cutoff': 5.6, 'top_schools_cutoff': 6.6,
+        'topic_weights': {'algebra': 32, 'geometry': 25, 'arithmetic': 15, 'hệ phương trình': 10, 'statistics': 8, 'functions': 5, 'number_theory': 5},
+    },
+}
+_DIFFICULTY_LABELS = {1: 'Dễ', 2: 'Trung bình', 3: 'Khá', 4: 'Khó', 5: 'Rất khó'}
+
+
+def _get_province_context(province: str | None) -> str:
+    if not province or province not in _PROVINCE_DATA:
+        return "National average THPT Math 2024: 6.51. Calibrate recommendations to general Vietnamese exam standards."
+    d = _PROVINCE_DATA[province]
+    label = _DIFFICULTY_LABELS.get(d['difficulty'], 'Trung bình')
+    return (
+        f"Province: {province} | Difficulty: {label} ({d['difficulty']}/5) | "
+        f"Typical Math cutoff: {d['typical_cutoff']} | Top schools require: {d['top_schools_cutoff']}+ | "
+        f"National avg: 6.51. Calibrate school recommendations to {province} standards specifically."
+    )
+
+
+def _strip_code_fence(text: str) -> str:
+    if text.startswith("```"):
+        parts = text.split("```")
+        text = parts[1] if len(parts) > 1 else text
+        if text.startswith("json"):
+            text = text[4:]
+    return text.strip()
+
+
+def build_analyze_prompt(
+    result: dict,
+    history: list[dict],
+    student_name: str = "",
+    wrong_questions: list[dict] = None,
+    school_recommendations: list[dict] = None,
+    exam_category: str = "",
+    user_profile: dict = None,
+    learner_archetype: str | None = None,
+    device_province: str | None = None,
+) -> str:
+    topic_breakdown = result.get("topicBreakdown", {})
+    weak_topics = [t for t, tb in topic_breakdown.items() if tb.get("accuracy", 1) < 0.6]
+
+    dynamic_parts = []
+    if student_name:
+        dynamic_parts.append(f"Học sinh: {student_name}")
+    dynamic_parts.append(f"Điểm: {result.get('score', 0)}/10")
+    dynamic_parts.append(f"Độ chính xác: {round(result.get('accuracy', 0) * 100)}%")
+    dynamic_parts.append(f"Chủ đề yếu (< 60%): {', '.join(weak_topics) or 'Không có'}")
+    dynamic_parts.append(f"Chi tiết theo chủ đề: {json.dumps(topic_breakdown, ensure_ascii=False)}")
+    if len(history) >= 2:
+        recent_scores = [r.get("score", 0) for r in history[-5:]]
+        dynamic_parts.append(f"Điểm gần đây: {recent_scores}")
+
+    if wrong_questions:
+        wrong_summary = [
+            {"topic": q.get("topic"), "difficulty": q.get("difficulty"), "question": q.get("question", "")[:80]}
+            for q in wrong_questions[:5]
+        ]
+        dynamic_parts.append(f"Câu sai ({len(wrong_questions)} câu, ví dụ): {json.dumps(wrong_summary, ensure_ascii=False)}")
+
+    grade = str((user_profile or {}).get("grade", ""))
+    province = (user_profile or {}).get("province", "") or (user_profile or {}).get("location", "")
+
+    if school_recommendations:
+        school_list = [
+            f"{s['school']['name']} ({s['matchStrength']}, điểm chuẩn Toán: {s['cutoff']})"
+            for s in school_recommendations[:6]
+        ]
+        # Derive school type from grade: ≤9 → high school (lớp 10), 10-12 → university
+        if grade and grade.isdigit() and int(grade) <= 9:
+            exam_type = "lớp 10"
+            school_type_note = "trường THPT"
+        else:
+            exam_type = "đại học/THPT"
+            school_type_note = "trường đại học/cao đẳng"
+        loc_note = f" tại {province}" if province else ""
+        dynamic_parts.append(
+            f"Trường gợi ý{loc_note} ({school_type_note}, kỳ thi {exam_type}): {'; '.join(school_list)}"
+        )
+
+    # Add grade + province context for personalized school recommendation prompt
+    if grade:
+        dynamic_parts.append(f"Lớp học sinh: {grade}")
+    if province:
+        dynamic_parts.append(f"Tỉnh/thành phố: {province}")
+    if learner_archetype:
+        dynamic_parts.append(f"Learner type: {learner_archetype}")
+
+    # Append per-province difficulty context (dynamic, not in static system prompt)
+    province_ctx = _get_province_context(province or None)
+    dynamic_parts.append(f"Provincial context: {province_ctx}")
+
+    # Device-detected location context — supplements (does not replace) user-selected province
+    if device_province:
+        note = f"Vị trí thiết bị phát hiện: {device_province}"
+        if device_province != province:
+            note += f" (khác với tỉnh trong hồ sơ: {province or 'chưa đặt'})"
+        dynamic_parts.append(
+            f"{note}. Dùng thông tin này để bổ sung nhận xét về đặc thù đề thi địa phương "
+            f"(trọng số chủ đề, mức độ cạnh tranh) trong phần insights và recommendations. "
+            f"Không thêm tên trường vào insights/recommendations — danh sách trường được hiển thị riêng."
+        )
+        if not province:
+            dynamic_parts.append(f"Device provincial context: {_get_province_context(device_province)}")
+
+    school_json_field = ""
+    if school_recommendations:
+        if grade and grade.isdigit() and int(grade) <= 9:
+            school_insight_hint = "Nhận xét ngắn 1-2 câu tổng quan về trường THPT phù hợp để thi vào lớp 10"
+            school_type_example = "THPT"
+        else:
+            school_insight_hint = "Nhận xét ngắn 1-2 câu tổng quan về trường đại học/cao đẳng phù hợp"
+            school_type_example = "Đại học"
+        school_json_field = (
+            f',\n  "school_insight": "{school_insight_hint}",'
+            f'\n  "schools": ['
+            f'\n    {{'
+            f'\n      "name": "Tên trường đầy đủ",'
+            f'\n      "score_range": "Ngưỡng điểm chuẩn Toán (vd: 7.5–8.5 điểm)",'
+            f'\n      "type": "{school_type_example}",'
+            f'\n      "region_note": "Tỉnh/thành của trường — quan hệ với tỉnh học sinh (cùng tỉnh/tỉnh lân cận/...)",'
+            f'\n      "note": "1 câu nhận xét tại sao phù hợp với điểm số này"'
+            f'\n    }}'
+            f'\n  ]  // Liệt kê 3-5 trường phù hợp nhất theo thứ tự ưu tiên'
+        )
+
+    prompt = "\n".join(dynamic_parts) + f"""
+
+Trả về JSON (không có text ngoài JSON):
+{{
+  "insights": "Nhận xét tổng quan 2-3 câu về kết quả thi",
+  "question_analysis": "Phân tích cụ thể các câu trả lời sai nếu có, chỉ ra điểm cần cải thiện (2-3 câu)",
+  "weak_topics": ["topic_key1", "topic_key2"],
+  "recommendations": ["khuyến nghị 1", "khuyến nghị 2", "khuyến nghị 3"]{school_json_field}
+}}"""
+    return prompt
+
+
+async def analyze_exam_result(
+    client: AsyncOpenAI,
+    result: dict,
+    history: list[dict],
+    student_name: str = "",
+    wrong_questions: list[dict] = None,
+    school_recommendations: list[dict] = None,
+    exam_category: str = "",
+    user_profile: dict = None,
+    learner_archetype: str | None = None,
+    device_province: str | None = None,
+) -> dict:
+    settings = get_settings()
+
+    prompt = build_analyze_prompt(
+        result, history, student_name,
+        wrong_questions=wrong_questions,
+        school_recommendations=school_recommendations,
+        exam_category=exam_category,
+        user_profile=user_profile,
+        learner_archetype=learner_archetype,
+        device_province=device_province,
+    )
+
+    response = await call_with_retry(
+        client,
+        model=settings.default_model,
+        max_tokens=1200,
+        messages=[
+            {"role": "system", "content": STATIC_EXAM_ANALYSIS_INSTRUCTIONS},
+            {"role": "user", "content": prompt},
+        ],
+    )
+
+    content = _strip_code_fence(response.choices[0].message.content or "{}")
+    return json.loads(content)

backend/app/agent/exam_explainer.py

@@ -0,0 +1,118 @@
+import json
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+
+THPT_CONTEXT = """
+Bối cảnh: Đây là kỳ thi THPT Quốc gia Việt Nam. Các câu hỏi thường có bẫy sau:
+- Nhầm lẫn giữa điều kiện cần và điều kiện đủ trong bài toán logarit, hàm số
+- Bỏ sót nghiệm ngoài miền xác định
+- Tính sai dấu khi khai triển công thức lượng giác
+- Nhầm chiều tích phân hoặc quên hằng số C
+Luôn gợi ý học sinh kiểm tra lại điều kiện trước khi kết luận.
+"""
+
+STATIC_EXPLAIN_INSTRUCTIONS = """Bạn là gia sư toán học chuyên ôn thi lớp 10 TPHCM. \
+Phân tích câu hỏi trắc nghiệm, xác định đáp án đúng bằng lập luận toán học, rồi giải thích ngắn gọn. \
+Trả lời bằng tiếng Việt."""
+
+LABELS = ["A", "B", "C", "D"]
+
+
+import re
+
+def _extract_json(text: str) -> str:
+    """Return the first {...} block found anywhere in the text."""
+    match = re.search(r'\{[^{}]*\}', text, re.DOTALL)
+    if match:
+        return match.group(0)
+    # Fallback: strip code fences and return
+    text = re.sub(r'^```(?:json)?\s*', '', text.strip())
+    text = re.sub(r'\s*```$', '', text)
+    return text.strip()
+
+
+_EXPLANATION_DEPTH_INSTRUCTIONS = {
+    "brief": "Giải thích ngắn gọn — chỉ 2-3 câu nêu bật ý chính.",
+    "detailed": "Giải thích đầy đủ, chi tiết để học sinh hiểu rõ.",
+    "step-by-step": "Trình bày giải thích theo các bước đánh số. Mỗi bước trên một dòng riêng.",
+}
+
+_ENCOURAGEMENT_INSTRUCTIONS = {
+    'minimal': 'Be concise and direct. Skip praise.',
+    'moderate': 'Brief encouragement is welcome.',
+    'high': 'Be warm and encouraging throughout.',
+}
+
+
+async def generate_explanation(
+    client: AsyncOpenAI,
+    question: dict,
+    chosen_index: int,
+    ai_preferences: dict | None = None,
+) -> dict:
+    settings = get_settings()
+
+    explanation_depth = (ai_preferences or {}).get("explanation_depth", "detailed")
+    depth_instruction = _EXPLANATION_DEPTH_INSTRUCTIONS.get(explanation_depth, _EXPLANATION_DEPTH_INSTRUCTIONS["detailed"])
+    encouragement_level = (ai_preferences or {}).get("encouragement_level", "moderate")
+    encouragement_instruction = _ENCOURAGEMENT_INSTRUCTIONS.get(encouragement_level, _ENCOURAGEMENT_INSTRUCTIONS["moderate"])
+    choices = question.get("choices", [])
+
+    # Ground truth from question data — never let AI guess the correct answer
+    correct_index = int(question.get("correct", 0))
+    correct_index = max(0, min(correct_index, len(choices) - 1))
+    base_explanation = question.get("explanation", "")
+
+    chosen_label = LABELS[chosen_index] if chosen_index < len(LABELS) else str(chosen_index)
+    correct_label = LABELS[correct_index] if correct_index < len(LABELS) else str(correct_index)
+
+    choices_text = "\n".join(
+        f"  {LABELS[i]}. {c}" for i, c in enumerate(choices) if i < len(LABELS)
+    )
+
+    # If the question already has an explanation, use it directly without an AI call
+    if base_explanation:
+        student_context = (
+            f"Bạn đã chọn đúng ({correct_label})! " if chosen_index == correct_index
+            else f"Bạn chọn {chosen_label}, đáp án đúng là {correct_label}. "
+        )
+        return {
+            "correct_index": correct_index,
+            "explanation": student_context + base_explanation,
+        }
+
+    # No pre-written explanation — ask AI to explain, but correct_index is already known
+    prompt = f"""Câu hỏi trắc nghiệm toán lớp 10:
+{question.get('question', '')}
+
+Các lựa chọn:
+{choices_text}
+
+Chủ đề: {question.get('topic', '')} | Mức độ: {question.get('difficulty', '')}
+Học sinh đã chọn: {chosen_label}
+Đáp án đúng: {correct_label} (index {correct_index}) — đây là sự thật, không được thay đổi.
+
+QUAN TRỌNG: Chỉ trả về JSON, không có bất kỳ văn bản nào khác trước hoặc sau.
+Giải thích ngắn gọn tại sao đáp án {correct_label} đúng:
+{{"correct_index": {correct_index}, "explanation": "<2–3 câu tiếng Việt giải thích, không dùng markdown>"}}"""
+
+    response = await call_with_retry(
+        client,
+        model=settings.haiku_model,
+        max_tokens=400,
+        messages=[
+            {"role": "system", "content": THPT_CONTEXT + STATIC_EXPLAIN_INSTRUCTIONS + "\n" + depth_instruction + "\n" + encouragement_instruction},
+            {"role": "user", "content": prompt},
+        ],
+    )
+
+    raw = response.choices[0].message.content or ""
+    content = _extract_json(raw)
+    try:
+        data = json.loads(content)
+        # Always use ground-truth correct_index regardless of what AI returns
+        data["correct_index"] = correct_index
+        return data
+    except (json.JSONDecodeError, ValueError):
+        return {"correct_index": correct_index, "explanation": raw.strip()}

backend/app/agent/fsrs.py

@@ -0,0 +1,59 @@
+"""
+FSRS v5 spaced-repetition algorithm — mirrors the frontend implementation exactly.
+
+Parameters (FSRS_W) are identical to exam-app/src/pages/ReviewSession.jsx so that
+server-computed next_review_date matches what the client would have computed.
+
+Quality scale (same as frontend):
+  1 = Đoán  (Again / forgot)
+  3 = Khá   (Good)
+  5 = Chắc  (Easy / remembered well)
+"""
+import math
+
+FSRS_W = [0.4, 0.6, 2.4, 5.8, 4.93, 0.94, 0.86, 0.01, 1.49, 0.14, 0.94, 2.18, 0.05, 0.34, 1.26, 0.29, 2.61]
+
+
+def fsrs_update(
+    stability: float,
+    difficulty: float,
+    elapsed: int,
+    quality: int,
+) -> tuple[float, float, int]:
+    """
+    Apply one FSRS review step and return (new_stability, new_difficulty, interval_days).
+
+    quality: 1 | 3 | 5  (frontend scale)
+    """
+    stability = max(0.5, float(stability))
+    difficulty = max(1.0, min(10.0, float(difficulty)))
+    elapsed = max(1, int(elapsed))
+
+    # Map frontend quality (1/3/5) to FSRS internal scale (1/3/4)
+    q = 1 if quality <= 1 else (3 if quality <= 3 else 4)
+
+    retrievability = math.exp(math.log(0.9) * elapsed / stability)
+
+    if q >= 3:
+        new_stability = stability * (
+            math.exp(FSRS_W[8])
+            * (11 - difficulty)
+            * math.pow(stability, -FSRS_W[9])
+            * (math.exp(FSRS_W[10] * (1 - retrievability)) - 1)
+            + 1
+        )
+    else:
+        new_stability = (
+            FSRS_W[11]
+            * math.pow(difficulty, -FSRS_W[12])
+            * (math.pow(stability + 1, FSRS_W[13]) - 1)
+            * math.exp(FSRS_W[14] * (1 - retrievability))
+        )
+
+    new_stability = max(0.5, new_stability)
+    # interval = round(new_stability) — the log(0.9)/log(0.9) terms cancel to 1.0
+    interval = max(1, round(new_stability))
+
+    new_difficulty = max(1.0, min(10.0, difficulty + FSRS_W[6] * (3 - q)))
+
+    return new_stability, new_difficulty, interval

backend/app/agent/hint_generator.py

@@ -0,0 +1,90 @@
+import json
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+
+THPT_CONTEXT = """
+Bối cảnh: Đây là kỳ thi THPT Quốc gia Việt Nam. Các câu hỏi thường có bẫy sau:
+- Nhầm lẫn giữa điều kiện cần và điều kiện đủ trong bài toán logarit, hàm số
+- Bỏ sót nghiệm ngoài miền xác định
+- Tính sai dấu khi khai triển công thức lượng giác
+- Nhầm chiều tích phân hoặc quên hằng số C
+Luôn gợi ý học sinh kiểm tra lại điều kiện trước khi kết luận.
+"""
+
+STATIC_HINT_INSTRUCTIONS = """Bạn là trợ lý AI của ứng dụng luyện thi toán lớp 10 TPHCM. \
+Hỗ trợ tạo nội dung giáo dục. Trả lời bằng tiếng Việt."""
+
+_DETAIL_LEVEL = {
+    1: "gợi ý nhẹ — chỉ gợi hướng tư duy, không tiết lộ bất kỳ thông tin về đáp án",
+    2: "gợi ý vừa — chỉ ra phương pháp giải cụ thể, vẫn không tiết lộ đáp án",
+    3: "gợi ý chi tiết — giải thích từng bước tiếp cận, nhưng để học sinh tự chọn đáp án",
+}
+
+
+def _strip_code_fence(text: str) -> str:
+    if text.startswith("```"):
+        parts = text.split("```")
+        text = parts[1] if len(parts) > 1 else text
+        if text.startswith("json"):
+            text = text[4:]
+    return text.strip()
+
+
+_HINT_STYLE_INSTRUCTIONS = {
+    "socratic": "Hướng dẫn bằng cách đặt câu hỏi gợi mở, KHÔNG tiết lộ đáp án — hãy để học sinh tự khám phá.",
+    "direct": "Đưa ra gợi ý trực tiếp, rõ ràng về cách tiếp cận từng bước. Hãy cụ thể và rõ ràng.",
+    "visual": "Trình bày gợi ý theo các bước đánh số rõ ràng. Dùng ký hiệu toán học chuẩn và nhãn bước rõ ràng.",
+}
+
+_ENCOURAGEMENT_INSTRUCTIONS = {
+    'minimal': 'Be concise and direct. Skip praise.',
+    'moderate': 'Brief encouragement is welcome.',
+    'high': 'Be warm and encouraging throughout.',
+}
+
+
+async def generate_hint(
+    client: AsyncOpenAI,
+    question: dict,
+    attempt_count: int = 1,
+    previous_hints: list[str] | None = None,
+    ai_preferences: dict | None = None,
+) -> dict:
+    settings = get_settings()
+    level = _DETAIL_LEVEL.get(min(attempt_count, 3), _DETAIL_LEVEL[3])
+
+    hint_style = (ai_preferences or {}).get("hint_style", "socratic")
+    style_instruction = _HINT_STYLE_INSTRUCTIONS.get(hint_style, _HINT_STYLE_INSTRUCTIONS["socratic"])
+    encouragement_level = (ai_preferences or {}).get("encouragement_level", "moderate")
+    encouragement_instruction = _ENCOURAGEMENT_INSTRUCTIONS.get(encouragement_level, _ENCOURAGEMENT_INSTRUCTIONS["moderate"])
+
+    prev_context = ""
+    if previous_hints:
+        shown = "\n".join(f"  Lần {i+1}: {h}" for i, h in enumerate(previous_hints))
+        prev_context = f"\nCác gợi ý đã cung cấp (KHÔNG lặp lại, phải tiến xa hơn):\n{shown}\n"
+
+    prompt = f"""Tôi cần bạn tạo một GỢI Ý ngắn (KHÔNG phải lời giải) cho câu hỏi toán sau.
+Yêu cầu ({level}): Đặt 1–2 câu hỏi gợi mở hoặc nhắc 1 khái niệm liên quan để học sinh tự suy nghĩ.
+Quy tắc bắt buộc:
+- Tối đa 2 câu, viết liền mạch, không xuống dòng
+- KHÔNG dùng markdown, KHÔNG dùng số thứ tự, KHÔNG dùng gạch đầu dòng
+- KHÔNG tiết lộ đáp án hay ký hiệu A/B/C/D
+Chủ đề: {question.get('topic', '')} | Mức độ: {question.get('difficulty', '')} | Lần {attempt_count}/3
+Câu hỏi: {question.get('question', '')}{prev_context}
+Trả về đúng định dạng JSON sau, không thêm text nào khác:
+{{"hint": "<1–2 câu gợi ý tiếng Việt, không markdown>", "difficulty_note": ""}}"""
+
+    response = await call_with_retry(
+        client,
+        model=settings.hint_model,
+        max_tokens=512,
+        messages=[
+            {"role": "system", "content": THPT_CONTEXT + STATIC_HINT_INSTRUCTIONS + "\n" + style_instruction + "\n" + encouragement_instruction},
+            {"role": "user", "content": prompt},
+        ],
+    )
+
+    raw = response.choices[0].message.content or ""
+    content = _strip_code_fence(raw)
+    return json.loads(content)

backend/app/agent/memory.py

@@ -0,0 +1,27 @@
+import json
+from openai import AsyncOpenAI
+from app.config import get_settings
+
+
+async def compress_conversation(
+    client: AsyncOpenAI,
+    messages: list[dict],
+) -> str:
+    settings = get_settings()
+    history_text = "\n".join(
+        f"{m['role'].upper()}: {m['content'] if isinstance(m['content'], str) else json.dumps(m['content'], ensure_ascii=False)}"
+        for m in messages
+        if m["role"] != "system"
+    )
+    response = await client.chat.completions.create(
+        model=settings.haiku_model,
+        max_tokens=512,
+        messages=[
+            {
+                "role": "system",
+                "content": "Tóm tắt ngắn gọn cuộc hội thoại dưới đây, giữ lại các thông tin quan trọng về yêu cầu và sản phẩm của khách.",
+            },
+            {"role": "user", "content": history_text},
+        ],
+    )
+    return response.choices[0].message.content or ""

backend/app/agent/study_planner.py

@@ -0,0 +1,131 @@
+import json
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+from app.agent.exam_analyzer import _PROVINCE_DATA
+
+STATIC_RECOVERY_PATH_INSTRUCTIONS = """Bạn là huấn luyện viên thi Toán lớp 9 vào lớp 10.
+Nhiệm vụ: nhìn vào điểm thi và từng câu sai cụ thể, xác định 1–2 lỗ hổng kiến thức quan trọng nhất, rồi tạo Recovery Path ngắn hạn (2–3 tuần) nhắm trực tiếp vào các lỗ hổng đó.
+
+Nguyên tắc bắt buộc:
+- score_gap: nêu khoảng cách điểm cụ thể và trường mục tiêu (nếu có). Không nói chung chung.
+- focus_areas: tối đa 2 chủ đề. Ưu tiên chủ đề sai nhiều nhất hoặc ảnh hưởng điểm nhất.
+- error_pattern: nêu đúng lỗi kỹ thuật cụ thể (không phải tên chủ đề). Ví dụ: "Sai ở bước xác định miền xác định logarit — xuất hiện 4/5 lần".
+- tasks: 2–3 nhiệm vụ luyện tập cụ thể, liên hệ trực tiếp đến lỗi đã xác định.
+- checkpoint: số câu cần trả lời đúng liên tiếp để coi là nắm vững (target: 3–5).
+- LATEX BẮT BUỘC: mọi ký hiệu toán học trong tasks/error_pattern PHẢI bọc trong $...$. Ví dụ: $\\Delta > 0$, $\\log_a x$, $x^2 - 5x + 6 = 0$.
+Trả lời bằng tiếng Việt. Luôn trả về JSON hợp lệ, không có text ngoài JSON."""
+
+
+def _strip_code_fence(text: str) -> str:
+    if text.startswith("```"):
+        parts = text.split("```")
+        text = parts[1] if len(parts) > 1 else text
+        if text.startswith("json"):
+            text = text[4:]
+    return text.strip()
+
+
+async def generate_study_plan(
+    client: AsyncOpenAI,
+    result: dict,
+    history: list[dict],
+    wrong_questions: list[dict] | None = None,
+    topic_miss_counts: dict | None = None,
+    student_name: str = "",
+    learner_archetype: str | None = None,
+    province: str = "",
+) -> dict:
+    settings = get_settings()
+
+    lines = []
+    if student_name:
+        lines.append(f"Học sinh: {student_name}")
+    lines.append(f"Điểm: {result.get('score', 0)}/10 ({round(result.get('accuracy', 0) * 100)}% đúng)")
+    lines.append(f"Số đề đã thi: {len(history)}")
+    if province and province in _PROVINCE_DATA:
+        p = _PROVINCE_DATA[province]
+        lines.append(
+            f"Tỉnh: {province} | Mức điểm an toàn: {p['typical_cutoff']} | "
+            f"Trường tốt yêu cầu: {p['top_schools_cutoff']}+ | "
+            f"Dùng các ngưỡng này để xác định khoảng cách điểm (score_gap) cụ thể cho học sinh."
+        )
+        if p.get("topic_weights"):
+            top_topics = sorted(p["topic_weights"].items(), key=lambda x: -x[1])[:5]
+            weights_str = ", ".join(f"{t} ({w}%)" for t, w in top_topics)
+            lines.append(
+                f"Phân bố chủ đề đề thi {province} (5 chủ đề chiếm tỷ trọng cao nhất): {weights_str}. "
+                f"Ưu tiên chọn focus_areas từ các chủ đề này vì chúng xuất hiện nhiều nhất trong đề thi tỉnh."
+            )
+    elif province:
+        lines.append(f"Tỉnh: {province}")
+
+    if wrong_questions:
+        if topic_miss_counts:
+            summary = ", ".join(f"{t}: {c} câu sai" for t, c in topic_miss_counts.items())
+            lines.append(f"Tổng hợp câu sai theo chủ đề: {summary}")
+
+        lines.append(
+            f"\nCâu sai đại diện ({len(wrong_questions)} câu — câu khó nhất mỗi chủ đề):"
+        )
+        for i, wq in enumerate(wrong_questions, 1):
+            topic = wq.get("topic", "")
+            diff = wq.get("difficulty", "")
+            q_text = wq.get("question", "")[:130]
+            correct = wq.get("correct_answer", "")
+            expl = wq.get("explanation", "")[:100]
+            lines.append(f"\nCâu {i} [{topic} / {diff}]: {q_text}")
+            lines.append(f"  Đáp án đúng: {correct}")
+            if expl:
+                lines.append(f"  Vì sao: {expl}")
+    else:
+        topic_breakdown = result.get("topicBreakdown", {})
+        weak = [t for t, tb in topic_breakdown.items() if tb.get("accuracy", 1) < 0.6]
+        lines.append(f"Chủ đề yếu: {', '.join(weak) or 'Không có'}")
+
+    prompt = "\n".join(lines) + """
+
+Tạo Recovery Path dựa trên dữ liệu trên.
+Trả về JSON (không có text ngoài JSON):
+{
+  "score_gap": "Mô tả khoảng cách điểm và mục tiêu cụ thể (1–2 câu)",
+  "focus_areas": [
+    {
+      "topic": "Tên chủ đề",
+      "error_pattern": "Mô tả lỗi kỹ thuật cụ thể",
+      "tasks": ["Nhiệm vụ luyện tập cụ thể 1", "Nhiệm vụ 2"],
+      "checkpoint": {"target": 5, "description": "Trả lời đúng 5 câu [chủ đề] liên tiếp"}
+    }
+  ],
+  "retake_note": "Sau khi hoàn thành Focus 1 → Thử lại đề thi để so sánh điểm"
+}"""
+
+    try:
+        response = await call_with_retry(
+            client,
+            model=settings.default_model,
+            max_tokens=1200,
+            messages=[
+                {"role": "system", "content": STATIC_RECOVERY_PATH_INSTRUCTIONS},
+                {"role": "user", "content": prompt},
+            ],
+        )
+        content = _strip_code_fence(response.choices[0].message.content or "{}")
+        return json.loads(content)
+    except Exception:
+        return {
+            "score_gap": "Phân tích cho thấy còn một số lỗ hổng cần bù. Tiếp tục ôn tập và thử lại đề thi.",
+            "focus_areas": [
+                {
+                    "topic": "Chủ đề yếu nhất",
+                    "error_pattern": "Xem lại giải thích từng câu sai để xác định lỗi cụ thể.",
+                    "tasks": [
+                        "Xem lại giải thích chi tiết từng câu sai",
+                        "Luyện 5–10 câu cùng dạng",
+                        "Ghi chú kỹ thuật cần nhớ",
+                    ],
+                    "checkpoint": {"target": 3, "description": "Trả lời đúng 3 câu cùng dạng liên tiếp"},
+                }
+            ],
+            "retake_note": "Sau khi luyện xong → Thử lại đề thi để so sánh điểm",
+        }

backend/app/auth.py

@@ -0,0 +1,41 @@
+import asyncio
+from datetime import datetime, timedelta, timezone
+
+import jwt
+import google.auth.exceptions
+import google.auth.transport.requests
+import google.oauth2.id_token
+
+from app.config import get_settings
+
+
+async def verify_google_token(id_token_str: str) -> dict:
+    """Verify a Google ID token and return its payload. Raises ValueError on failure."""
+    settings = get_settings()
+    try:
+        payload = await asyncio.to_thread(
+            google.oauth2.id_token.verify_oauth2_token,
+            id_token_str,
+            google.auth.transport.requests.Request(),
+            settings.google_client_id,
+        )
+        return payload
+    except google.auth.exceptions.GoogleAuthError as exc:
+        raise ValueError(f"Invalid or expired Google token: {exc}") from exc
+
+
+def create_jwt(user_id: int) -> str:
+    settings = get_settings()
+    now = datetime.now(tz=timezone.utc)
+    payload = {
+        "sub": str(user_id),
+        "iat": now,
+        "exp": now + timedelta(days=7),
+        "aud": "exam-app",
+    }
+    return jwt.encode(payload, settings.jwt_secret, algorithm="HS256")
+
+
+def decode_jwt(token: str) -> dict:
+    settings = get_settings()
+    return jwt.decode(token, settings.jwt_secret, algorithms=["HS256"], audience="exam-app")

backend/app/config.py

@@ -0,0 +1,90 @@
+from functools import lru_cache
+from pathlib import Path
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# Resolve .env relative to this file so it works regardless of CWD (e.g. npm run dev from repo root)
+_ENV_FILE = Path(__file__).parent.parent / ".env"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=str(_ENV_FILE), env_file_encoding="utf-8", extra="ignore")
+
+    anthropic_base_url: str = "https://ai-router.locdo.tech"
+    anthropic_auth_token: str
+
+    anthropic_default_opus_model: str = "claude-opus-4.6"
+    anthropic_default_sonnet_model: str = "claude-sonnet-4.6"
+    anthropic_default_haiku_model: str = "claude-haiku-4.5"
+    anthropic_default_hint_model: str = "claude-haiku-4.5"
+
+    allowed_origins: str = "http://localhost:5173,https://exam-app-ey0.pages.dev"
+    database_url: str = ""
+    # Set to "true" to run the background wiki crawl on startup.
+    # Keep "false" on HF Spaces until local testing is complete.
+    crawl_auto_seed_enabled: bool = False
+    # Set to "true" to wipe wiki_units and re-crawl everything from scratch.
+    # The app self-disables this flag via the HF Spaces API after one successful run.
+    crawl_force_reseed: bool = False
+    # Set to "true" to crawl only topics that have zero wiki units (gap-fill).
+    # Idempotent: re-runs are safe — the zero-unit check is the gate.
+    crawl_gap_fill_enabled: bool = False
+    # Set to "true" to fix non-canonical topic/type labels and remove content duplicates on startup.
+    # Self-disables via HF Spaces API after one successful run.
+    wiki_sanitize_enabled: bool = False
+    # Set to "true" to translate English wiki units (exam_upload source) to Vietnamese.
+    # Self-disables via HF Spaces API after one successful run.
+    wiki_fix_english_enabled: bool = False
+    embedding_model_name: str = "BAAI/bge-m3"
+    google_client_id: str = ""
+    jwt_secret: str = ""
+    admin_key: str = ""
+    admin_master_secret: str = ""
+    admin_key_rotation_period: str = "weekly"
+    admin_key_log_path: str = "./admin_keys.txt"
+    admin_key_log_enabled: bool = True
+    admin_key_webhook_url: str = ""
+    cron_secret: str = ""
+    sqlite_path: str = "/data/app.db"
+    payment_bank_name: str = ""
+    payment_account_number: str = ""
+    payment_account_name: str = ""
+
+    def __init__(self, **data):
+        super().__init__(**data)
+        if not self.jwt_secret:
+            raise RuntimeError("JWT_SECRET must be set in environment variables")
+        if len(self.jwt_secret) < 32:
+            raise RuntimeError("JWT_SECRET must be at least 32 characters")
+        if self.admin_master_secret and len(self.admin_master_secret) < 32:
+            raise RuntimeError("ADMIN_MASTER_SECRET must be at least 32 characters if set")
+        if self.cron_secret and len(self.cron_secret) < 32:
+            raise RuntimeError("CRON_SECRET must be at least 32 characters if set")
+    embedding_dim: int = 1024
+    use_sqlite_vec: bool = True
+    vector_top_k: int = 20
+    crag_threshold: float = 0.20
+
+    @property
+    def allowed_origins_list(self) -> list[str]:
+        return [o.strip() for o in self.allowed_origins.split(",")]
+
+    @property
+    def default_model(self) -> str:
+        return self.anthropic_default_sonnet_model
+
+    @property
+    def opus_model(self) -> str:
+        return self.anthropic_default_opus_model
+
+    @property
+    def haiku_model(self) -> str:
+        return self.anthropic_default_haiku_model
+
+    @property
+    def hint_model(self) -> str:
+        return self.anthropic_default_hint_model
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

backend/app/data/concepts.py

@@ -0,0 +1,503 @@
+"""
+Concept taxonomy for the Zenith Learning Graph — 62 concepts, grades 9–12.
+
+Each concept has:
+  prerequisite_ids  — edges pointing from required → this concept (DAG)
+  exam_weight       — relative THPT exam frequency (1.0 = rare, 5.0 = very common)
+  bloom_ceiling     — highest Bloom's level typically reached for this concept
+  topic             — canonical topic label (matches wiki_units.topic)
+
+Edge semantics: "B requires A" means A.prerequisite_ids is upstream of B,
+i.e. A → B is encoded as B.prerequisite_ids includes A.
+"""
+
+CONCEPTS: list[dict] = [
+
+    # ── Grade 9 foundation ────────────────────────────────────────────────────
+
+    {
+        "id": "linear_eq",
+        "name": "Linear Equations",
+        "name_vi": "Phương trình bậc nhất",
+        "grade": 9, "topic": "algebra",
+        "prerequisite_ids": [],
+        "exam_weight": 2.0, "bloom_ceiling": 3,
+    },
+    {
+        "id": "linear_systems",
+        "name": "Systems of Linear Equations",
+        "name_vi": "Hệ phương trình bậc nhất",
+        "grade": 9, "topic": "algebra",
+        "prerequisite_ids": ["linear_eq"],
+        "exam_weight": 2.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "quad_eq",
+        "name": "Quadratic Equations",
+        "name_vi": "Phương trình bậc hai",
+        "grade": 9, "topic": "algebra",
+        "prerequisite_ids": ["linear_eq"],
+        "exam_weight": 3.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "radicals",
+        "name": "Radical Expressions",
+        "name_vi": "Căn thức và biến đổi",
+        "grade": 9, "topic": "algebra",
+        "prerequisite_ids": ["linear_eq"],
+        "exam_weight": 2.0, "bloom_ceiling": 3,
+    },
+    {
+        "id": "inequalities",
+        "name": "Inequalities",
+        "name_vi": "Bất phương trình",
+        "grade": 9, "topic": "algebra",
+        "prerequisite_ids": ["linear_eq", "quad_eq"],
+        "exam_weight": 2.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "basic_geo",
+        "name": "Basic Plane Geometry",
+        "name_vi": "Hình học phẳng cơ bản",
+        "grade": 9, "topic": "geometry",
+        "prerequisite_ids": [],
+        "exam_weight": 2.0, "bloom_ceiling": 4,
+    },
+    {
+        "id": "triangles",
+        "name": "Triangles",
+        "name_vi": "Tam giác và các tính chất",
+        "grade": 9, "topic": "geometry",
+        "prerequisite_ids": ["basic_geo"],
+        "exam_weight": 2.5, "bloom_ceiling": 5,
+    },
+    {
+        "id": "circles",
+        "name": "Circles",
+        "name_vi": "Đường tròn",
+        "grade": 9, "topic": "geometry",
+        "prerequisite_ids": ["basic_geo", "triangles"],
+        "exam_weight": 2.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "stats_basic",
+        "name": "Basic Statistics",
+        "name_vi": "Thống kê cơ bản",
+        "grade": 9, "topic": "statistics",
+        "prerequisite_ids": [],
+        "exam_weight": 1.5, "bloom_ceiling": 3,
+    },
+    {
+        "id": "prob_basic",
+        "name": "Basic Probability",
+        "name_vi": "Xác suất cơ bản",
+        "grade": 9, "topic": "probability",
+        "prerequisite_ids": ["stats_basic"],
+        "exam_weight": 2.0, "bloom_ceiling": 4,
+    },
+    {
+        "id": "combinatorics",
+        "name": "Combinatorics",
+        "name_vi": "Tổ hợp và chỉnh hợp",
+        "grade": 9, "topic": "combinatorics",
+        "prerequisite_ids": [],
+        "exam_weight": 2.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "number_theory",
+        "name": "Number Theory",
+        "name_vi": "Lý thuyết số cơ bản",
+        "grade": 9, "topic": "number_theory",
+        "prerequisite_ids": [],
+        "exam_weight": 1.5, "bloom_ceiling": 5,
+    },
+    {
+        "id": "sets",
+        "name": "Sets",
+        "name_vi": "Tập hợp",
+        "grade": 9, "topic": "algebra",
+        "prerequisite_ids": [],
+        "exam_weight": 1.0, "bloom_ceiling": 3,
+    },
+
+    # ── Grade 10 ──────────────────────────────────────────────────────────────
+
+    {
+        "id": "linear_func",
+        "name": "Linear Functions",
+        "name_vi": "Hàm số bậc nhất",
+        "grade": 10, "topic": "functions_and_graphs",
+        "prerequisite_ids": ["linear_eq"],
+        "exam_weight": 2.0, "bloom_ceiling": 4,
+    },
+    {
+        "id": "quad_func",
+        "name": "Quadratic Functions & Parabola",
+        "name_vi": "Hàm số bậc hai và parabol",
+        "grade": 10, "topic": "functions_and_graphs",
+        "prerequisite_ids": ["quad_eq"],
+        "exam_weight": 2.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "coord_geo",
+        "name": "Coordinate Geometry",
+        "name_vi": "Hình học tọa độ Oxy",
+        "grade": 10, "topic": "geometry",
+        "prerequisite_ids": ["linear_eq", "basic_geo"],
+        "exam_weight": 2.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "trig_basic",
+        "name": "Basic Trigonometry",
+        "name_vi": "Lượng giác cơ bản",
+        "grade": 10, "topic": "trigonometry",
+        "prerequisite_ids": ["basic_geo", "triangles"],
+        "exam_weight": 2.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "vectors",
+        "name": "Plane Vectors",
+        "name_vi": "Vectơ phẳng",
+        "grade": 10, "topic": "geometry",
+        "prerequisite_ids": ["coord_geo"],
+        "exam_weight": 2.0, "bloom_ceiling": 4,
+    },
+    {
+        "id": "sequences",
+        "name": "Sequences & Series",
+        "name_vi": "Dãy số",
+        "grade": 10, "topic": "algebra",
+        "prerequisite_ids": ["quad_eq"],
+        "exam_weight": 2.0, "bloom_ceiling": 4,
+    },
+    {
+        "id": "financial_math",
+        "name": "Financial Mathematics",
+        "name_vi": "Toán tài chính",
+        "grade": 10, "topic": "algebra",
+        "prerequisite_ids": ["sequences"],
+        "exam_weight": 1.5, "bloom_ceiling": 3,
+    },
+
+    # ── Grade 11 ──────────────────────────────────────────────────────────────
+
+    {
+        "id": "trig_advanced",
+        "name": "Advanced Trigonometry",
+        "name_vi": "Lượng giác nâng cao — công thức cộng và hàm",
+        "grade": 11, "topic": "trigonometry",
+        "prerequisite_ids": ["trig_basic"],
+        "exam_weight": 3.0, "bloom_ceiling": 4,
+    },
+    {
+        "id": "trig_eq",
+        "name": "Trigonometric Equations",
+        "name_vi": "Phương trình lượng giác",
+        "grade": 11, "topic": "trigonometry",
+        "prerequisite_ids": ["trig_advanced"],
+        "exam_weight": 3.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "exponential",
+        "name": "Exponential Functions",
+        "name_vi": "Hàm số mũ và hàm số lũy thừa",
+        "grade": 11, "topic": "algebra",
+        "prerequisite_ids": ["quad_func"],
+        "exam_weight": 3.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "logarithm",
+        "name": "Logarithms",
+        "name_vi": "Logarit và hàm logarit",
+        "grade": 11, "topic": "algebra",
+        "prerequisite_ids": ["exponential"],
+        "exam_weight": 3.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "exp_log_eq",
+        "name": "Exponential & Logarithmic Equations",
+        "name_vi": "Phương trình mũ và logarit",
+        "grade": 11, "topic": "algebra",
+        "prerequisite_ids": ["logarithm", "exponential"],
+        "exam_weight": 4.0, "bloom_ceiling": 4,
+    },
+    {
+        "id": "exp_log_ineq",
+        "name": "Exponential & Logarithmic Inequalities",
+        "name_vi": "Bất phương trình mũ và logarit",
+        "grade": 11, "topic": "algebra",
+        "prerequisite_ids": ["exp_log_eq", "inequalities"],
+        "exam_weight": 3.0, "bloom_ceiling": 5,
+    },
+    {
+        "id": "spatial_geo",
+        "name": "Spatial Geometry — Lines & Planes",
+        "name_vi": "Hình học không gian — đường thẳng và mặt phẳng",
+        "grade": 11, "topic": "geometry",
+        "prerequisite_ids": ["basic_geo", "vectors"],
+        "exam_weight": 3.0, "bloom_ceiling": 4,
+    },
+    {
+        "id": "spatial_solids",
+        "name": "Spatial Geometry — Polyhedra & Solids",
+        "name_vi": "Hình học không gian — khối đa diện và hình tròn xoay",
+        "grade": 11, "topic": "geometry",
+        "prerequisite_ids": ["spatial_geo"],
+        "exam_weight": 3.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "comb_advanced",
+        "name": "Advanced Combinatorics",
+        "name_vi": "Tổ hợp nâng cao — nhị thức Newton",
+        "grade": 11, "topic": "combinatorics",
+        "prerequisite_ids": ["combinatorics"],
+        "exam_weight": 2.5, "bloom_ceiling": 5,
+    },
+    {
+        "id": "prob_advanced",
+        "name": "Advanced Probability",
+        "name_vi": "Xác suất nâng cao — xác suất có điều kiện",
+        "grade": 11, "topic": "probability",
+        "prerequisite_ids": ["prob_basic", "comb_advanced"],
+        "exam_weight": 3.0, "bloom_ceiling": 5,
+    },
+    {
+        "id": "complex_numbers",
+        "name": "Complex Numbers",
+        "name_vi": "Số phức",
+        "grade": 11, "topic": "algebra",
+        "prerequisite_ids": ["quad_eq", "trig_basic"],
+        "exam_weight": 1.5, "bloom_ceiling": 4,
+    },
+
+    # ── Grade 12 — Functions & Calculus ──────────────────────────────────────
+
+    {
+        "id": "func_monotone",
+        "name": "Function Monotonicity",
+        "name_vi": "Tính đơn điệu của hàm số",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["quad_func", "logarithm"],
+        "exam_weight": 4.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "func_extrema",
+        "name": "Local Extrema",
+        "name_vi": "Cực trị của hàm số",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["func_monotone"],
+        "exam_weight": 4.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "func_asymptote",
+        "name": "Asymptotes",
+        "name_vi": "Đường tiệm cận",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["func_monotone"],
+        "exam_weight": 3.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "func_graph",
+        "name": "Function Graph Sketching",
+        "name_vi": "Khảo sát và vẽ đồ thị hàm số",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["func_extrema", "func_asymptote"],
+        "exam_weight": 4.0, "bloom_ceiling": 5,
+    },
+    {
+        "id": "derivative_rules",
+        "name": "Differentiation Rules",
+        "name_vi": "Quy tắc tính đạo hàm",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["linear_func", "exponential", "trig_basic"],
+        "exam_weight": 4.0, "bloom_ceiling": 3,
+    },
+    {
+        "id": "derivative_apps",
+        "name": "Derivative Applications",
+        "name_vi": "Ứng dụng đạo hàm — tốc độ, tối ưu",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["derivative_rules", "func_extrema"],
+        "exam_weight": 3.5, "bloom_ceiling": 5,
+    },
+    {
+        "id": "global_extrema",
+        "name": "Global Extrema on Closed Interval",
+        "name_vi": "GTLN và GTNN trên đoạn",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["func_extrema", "derivative_rules"],
+        "exam_weight": 4.0, "bloom_ceiling": 4,
+    },
+
+    # ── Grade 12 — Integrals ──────────────────────────────────────────────────
+
+    {
+        "id": "antiderivative",
+        "name": "Antiderivatives",
+        "name_vi": "Nguyên hàm",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["derivative_rules"],
+        "exam_weight": 4.0, "bloom_ceiling": 3,
+    },
+    {
+        "id": "definite_integral",
+        "name": "Definite Integrals",
+        "name_vi": "Tích phân xác định — Newton-Leibniz",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["antiderivative"],
+        "exam_weight": 4.5, "bloom_ceiling": 3,
+    },
+    {
+        "id": "integral_area",
+        "name": "Area Under a Curve",
+        "name_vi": "Ứng dụng tích phân — diện tích hình phẳng",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["definite_integral"],
+        "exam_weight": 4.0, "bloom_ceiling": 4,
+    },
+    {
+        "id": "integral_volume",
+        "name": "Volume of Revolution",
+        "name_vi": "Ứng dụng tích phân — thể tích vật thể tròn xoay",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["integral_area"],
+        "exam_weight": 3.0, "bloom_ceiling": 5,
+    },
+    {
+        "id": "integral_by_parts",
+        "name": "Integration by Parts",
+        "name_vi": "Tích phân từng phần",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["antiderivative"],
+        "exam_weight": 2.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "integral_substitution",
+        "name": "Integration by Substitution",
+        "name_vi": "Tích phân bằng phương pháp đổi biến",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["antiderivative"],
+        "exam_weight": 3.0, "bloom_ceiling": 4,
+    },
+
+    # ── Grade 12 — 3D Geometry (Oxyz) ─────────────────────────────────────────
+
+    {
+        "id": "oxyz_coords",
+        "name": "Oxyz Coordinate System",
+        "name_vi": "Hệ tọa độ không gian Oxyz",
+        "grade": 12, "topic": "geometry",
+        "prerequisite_ids": ["spatial_geo", "vectors"],
+        "exam_weight": 3.5, "bloom_ceiling": 3,
+    },
+    {
+        "id": "oxyz_plane",
+        "name": "Planes in Space",
+        "name_vi": "Phương trình mặt phẳng",
+        "grade": 12, "topic": "geometry",
+        "prerequisite_ids": ["oxyz_coords"],
+        "exam_weight": 4.0, "bloom_ceiling": 4,
+    },
+    {
+        "id": "oxyz_line",
+        "name": "Lines in Space",
+        "name_vi": "Phương trình đường thẳng trong không gian",
+        "grade": 12, "topic": "geometry",
+        "prerequisite_ids": ["oxyz_coords"],
+        "exam_weight": 3.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "oxyz_distance",
+        "name": "Distance & Angle in Space",
+        "name_vi": "Khoảng cách và góc trong không gian",
+        "grade": 12, "topic": "geometry",
+        "prerequisite_ids": ["oxyz_plane", "oxyz_line"],
+        "exam_weight": 4.0, "bloom_ceiling": 5,
+    },
+    {
+        "id": "oxyz_sphere",
+        "name": "Sphere Equation",
+        "name_vi": "Phương trình mặt cầu",
+        "grade": 12, "topic": "geometry",
+        "prerequisite_ids": ["oxyz_coords"],
+        "exam_weight": 3.0, "bloom_ceiling": 4,
+    },
+
+    # ── Grade 12 — Probability & Statistics ──────────────────────────────────
+
+    {
+        "id": "bayes",
+        "name": "Bayes' Theorem",
+        "name_vi": "Công thức Bayes và xác suất toàn phần",
+        "grade": 12, "topic": "probability",
+        "prerequisite_ids": ["prob_advanced"],
+        "exam_weight": 3.5, "bloom_ceiling": 5,
+    },
+    {
+        "id": "binomial_dist",
+        "name": "Binomial Distribution",
+        "name_vi": "Phân phối nhị thức",
+        "grade": 12, "topic": "probability",
+        "prerequisite_ids": ["comb_advanced", "prob_advanced"],
+        "exam_weight": 2.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "normal_dist",
+        "name": "Normal Distribution",
+        "name_vi": "Phân phối chuẩn và ứng dụng",
+        "grade": 12, "topic": "statistics",
+        "prerequisite_ids": ["binomial_dist", "stats_basic"],
+        "exam_weight": 2.0, "bloom_ceiling": 4,
+    },
+
+    # ── Advanced / Cross-domain ───────────────────────────────────────────────
+
+    {
+        "id": "lhopital",
+        "name": "L'Hôpital's Rule",
+        "name_vi": "Quy tắc L'Hôpital",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["derivative_rules"],
+        "exam_weight": 1.5, "bloom_ceiling": 4,
+    },
+    {
+        "id": "optimization",
+        "name": "Optimization Problems",
+        "name_vi": "Bài toán tối ưu hóa thực tế",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["derivative_apps", "global_extrema"],
+        "exam_weight": 4.0, "bloom_ceiling": 6,
+    },
+    {
+        "id": "math_induction",
+        "name": "Mathematical Induction",
+        "name_vi": "Quy nạp toán học",
+        "grade": 11, "topic": "algebra",
+        "prerequisite_ids": ["sequences"],
+        "exam_weight": 1.5, "bloom_ceiling": 6,
+    },
+    {
+        "id": "coordinate_circle",
+        "name": "Circle Equation in Oxy",
+        "name_vi": "Phương trình đường tròn trong mặt phẳng tọa độ",
+        "grade": 10, "topic": "geometry",
+        "prerequisite_ids": ["coord_geo", "circles"],
+        "exam_weight": 3.0, "bloom_ceiling": 4,
+    },
+    {
+        "id": "conic_sections",
+        "name": "Conic Sections",
+        "name_vi": "Elip, hypebol, parabol trong tọa độ",
+        "grade": 12, "topic": "geometry",
+        "prerequisite_ids": ["coord_geo", "quad_func"],
+        "exam_weight": 2.5, "bloom_ceiling": 5,
+    },
+    {
+        "id": "func_rational",
+        "name": "Rational Functions",
+        "name_vi": "Hàm số phân thức bậc nhất trên bậc nhất",
+        "grade": 12, "topic": "calculus",
+        "prerequisite_ids": ["func_asymptote", "derivative_rules"],
+        "exam_weight": 4.0, "bloom_ceiling": 4,
+    },
+]

backend/app/data/question_answers.json

@@ -0,0 +1 @@
+{"q_amc8_001":0,"q_amc8_002":0,"q_amc8_003":0,"q_amc8_004":0,"q_amc8_005":0,"q_amc8_006":0,"q_amc8_007":0,"q_amc8_008":0,"q_amc8_009":0,"q_amc8_010":0,"q_amc8_011":0,"q_amc8_012":0,"q_amc8_013":0,"q_amc8_014":0,"q_amc8_015":0,"q_amc8_016":0,"q_amc8_017":0,"q_amc8_018":0,"q_amc8_019":0,"q_amc8_020":0,"q_amc10_001":0,"q_amc10_002":0,"q_amc10_003":0,"q_amc10_004":0,"q_amc10_005":0,"q_amc10_006":0,"q_amc10_007":0,"q_amc10_008":0,"q_amc10_009":0,"q_amc10_010":0,"q_amc10_011":0,"q_amc10_012":0,"q_amc10_013":0,"q_amc10_014":0,"q_amc10_015":0,"q_amc10_016":0,"q_amc10_017":0,"q_amc10_018":0,"q_amc10_019":0,"q_amc10_020":0,"q_gcse_001":0,"q_gcse_002":0,"q_gcse_003":0,"q_gcse_004":0,"q_gcse_005":0,"q_gcse_006":0,"q_gcse_007":0,"q_gcse_008":0,"q_gcse_009":0,"q_gcse_010":0,"q_gcse_011":0,"q_gcse_012":0,"q_gcse_013":0,"q_gcse_014":0,"q_gcse_015":0,"q_gcse_016":0,"q_gcse_017":0,"q_gcse_018":0,"q_gcse_019":0,"q_gcse_020":0,"q_sgol_001":0,"q_sgol_002":0,"q_sgol_003":0,"q_sgol_004":0,"q_sgol_005":0,"q_sgol_006":0,"q_sgol_007":0,"q_sgol_008":0,"q_sgol_009":0,"q_sgol_010":0,"q_sgol_011":0,"q_sgol_012":0,"q_sgol_013":0,"q_sgol_014":0,"q_sgol_015":0,"q_sgol_016":0,"q_sgol_017":0,"q_sgol_018":0,"q_sgol_019":0,"q_sgol_020":0,"q_amc_au_001":0,"q_amc_au_002":0,"q_amc_au_003":0,"q_amc_au_004":0,"q_amc_au_005":0,"q_amc_au_006":0,"q_amc_au_007":0,"q_amc_au_008":0,"q_amc_au_009":0,"q_amc_au_010":0,"q_amc_au_011":0,"q_amc_au_012":0,"q_amc_au_013":0,"q_amc_au_014":0,"q_amc_au_015":0,"q_amc_au_016":0,"q_amc_au_017":0,"q_amc_au_018":0,"q_amc_au_019":0,"q_amc_au_020":0,"q_vn_hn_001":0,"q_vn_hn_002":0,"q_vn_hn_003":0,"q_vn_hn_004":0,"q_vn_hn_005":0,"q_vn_hn_006":0,"q_vn_hn_007":0,"q_vn_hn_008":0,"q_vn_hn_009":0,"q_vn_hn_010":0,"q_vn_hn_011":0,"q_vn_hn_012":0,"q_vn_hn_013":0,"q_vn_hn_014":0,"q_vn_hn_015":0,"q_vn_hn_016":0,"q_vn_hn_017":0,"q_vn_hn_018":0,"q_vn_hn_019":0,"q_vn_hn_020":0,"q_vn_hcmc_001":0,"q_vn_hcmc_002":0,"q_vn_hcmc_003":0,"q_vn_hcmc_004":0,"q_vn_hcmc_005":0,"q_vn_hcmc_006":0,"q_vn_hcmc_007":0,"q_vn_hcmc_008":0,"q_vn_hcmc_009":0,"q_vn_hcmc_010":0,"q_vn_hcmc_011":0,"q_vn_hcmc_012":0,"q_vn_hcmc_013":0,"q_vn_hcmc_014":0,"q_vn_hcmc_015":0,"q_vn_hcmc_016":0,"q_vn_hcmc_017":0,"q_vn_hcmc_018":0,"q_vn_hcmc_019":0,"q_vn_hcmc_020":0,"q_vn_dn_001":0,"q_vn_dn_002":0,"q_vn_dn_003":0,"q_vn_dn_004":0,"q_vn_dn_005":0,"q_vn_dn_006":0,"q_vn_dn_007":0,"q_vn_dn_008":0,"q_vn_dn_009":0,"q_vn_dn_010":0,"q_vn_dn_011":0,"q_vn_dn_012":0,"q_vn_dn_013":0,"q_vn_dn_014":0,"q_vn_dn_015":0,"q_vn_dn_016":0,"q_vn_dn_017":0,"q_vn_dn_018":0,"q_vn_dn_019":0,"q_vn_dn_020":0,"q_vn_hp_001":0,"q_vn_hp_002":0,"q_vn_hp_003":0,"q_vn_hp_004":0,"q_vn_hp_005":0,"q_vn_hp_006":0,"q_vn_hp_007":0,"q_vn_hp_008":0,"q_vn_hp_009":0,"q_vn_hp_010":0,"q_vn_hp_011":0,"q_vn_hp_012":0,"q_vn_hp_013":0,"q_vn_hp_014":0,"q_vn_hp_015":0,"q_vn_hp_016":0,"q_vn_hp_017":0,"q_vn_hp_018":0,"q_vn_hp_019":0,"q_vn_hp_020":0,"q_vn_bgd_001":0,"q_vn_bgd_002":0,"q_vn_bgd_003":0,"q_vn_bgd_004":0,"q_vn_bgd_005":0,"q_vn_bgd_006":0,"q_vn_bgd_007":0,"q_vn_bgd_008":0,"q_vn_bgd_009":0,"q_vn_bgd_010":0,"q_vn_bgd_011":0,"q_vn_bgd_012":0,"q_vn_bgd_013":0,"q_vn_bgd_014":0,"q_vn_bgd_015":0,"q_vn_bgd_016":0,"q_vn_bgd_017":0,"q_vn_bgd_018":0,"q_vn_bgd_019":0,"q_vn_bgd_020":0,"q_thpt24_001":2,"q_thpt24_002":2,"q_thpt24_003":1,"q_thpt24_004":2,"q_thpt24_005":0,"q_thpt24_006":1,"q_thpt24_007":1,"q_thpt24_008":2,"q_thpt24_009":1,"q_thpt24_010":1,"q_thpt24_011":2,"q_thpt24_012":0,"q_thpt24_013":0,"q_thpt24_014":1,"q_thpt24_015":1,"q_thpt24_016":0,"q_thpt24_017":1,"q_thpt24_018":2,"q_thpt24_019":1,"q_thpt24_020":0,"q_thpt24_021":1,"q_thpt24_022":2,"q_thpt24_023":2,"q_thpt24_024":0,"q_thpt24_025":0,"q_thpt24_026":1,"q_thpt24_027":1,"q_thpt24_028":1,"q_thpt24_029":1,"q_thpt24_030":1,"q_thpt24_031":1,"q_thpt24_032":2,"q_thpt24_033":1,"q_thpt24_034":1,"q_thpt24_035":2,"q_thpt24_036":2,"q_thpt24_037":0,"q_thpt24_038":1,"q_thpt24_039":1,"q_thpt24_040":3,"q_thpt24_041":1,"q_thpt24_042":1,"q_thpt24_043":1,"q_thpt24_044":2,"q_thpt24_045":1,"q_thpt24_046":1,"q_thpt24_047":1,"q_thpt24_048":2,"q_thpt24_049":1,"q_thpt24_050":2,"q_thpt23_001":0,"q_thpt23_002":1,"q_thpt23_003":2,"q_thpt23_004":0,"q_thpt23_005":1,"q_thpt23_006":0,"q_thpt23_007":2,"q_thpt23_008":1,"q_thpt23_009":1,"q_thpt23_010":1,"q_thpt23_011":0,"q_thpt23_012":1,"q_thpt23_013":0,"q_thpt23_014":1,"q_thpt23_015":0,"q_thpt23_016":2,"q_thpt23_017":1,"q_thpt23_018":1,"q_thpt23_019":1,"q_thpt23_020":0,"q_thpt23_021":2,"q_thpt23_022":2,"q_thpt23_023":1,"q_thpt23_024":1,"q_thpt23_025":0,"q_thpt23_026":2,"q_thpt23_027":0,"q_thpt23_028":2,"q_thpt23_029":1,"q_thpt23_030":2,"q_thpt23_031":1,"q_thpt23_032":0,"q_thpt23_033":0,"q_thpt23_034":1,"q_thpt23_035":1,"q_thpt23_036":1,"q_thpt23_037":0,"q_thpt23_038":2,"q_thpt23_039":1,"q_thpt23_040":1,"q_thpt23_041":0,"q_thpt23_042":3,"q_thpt23_043":1,"q_thpt23_044":3,"q_thpt23_045":2,"q_thpt23_046":1,"q_thpt23_047":2,"q_thpt23_048":1,"q_thpt23_049":0,"q_thpt23_050":2,"q_thpt22_001":0,"q_thpt22_002":1,"q_thpt22_003":0,"q_thpt22_004":0,"q_thpt22_005":0,"q_thpt22_006":0,"q_thpt22_007":2,"q_thpt22_008":1,"q_thpt22_009":2,"q_thpt22_010":1,"q_thpt22_011":0,"q_thpt22_012":0,"q_thpt22_013":2,"q_thpt22_014":1,"q_thpt22_015":1,"q_thpt22_016":1,"q_thpt22_017":0,"q_thpt22_018":1,"q_thpt22_019":0,"q_thpt22_020":0,"q_thpt22_021":0,"q_thpt22_022":1,"q_thpt22_023":2,"q_thpt22_024":1,"q_thpt22_025":1,"q_thpt22_026":1,"q_thpt22_027":1,"q_thpt22_028":0,"q_thpt22_029":1,"q_thpt22_030":1,"q_thpt22_031":1,"q_thpt22_032":1,"q_thpt22_033":2,"q_thpt22_034":2,"q_thpt22_035":0,"q_thpt22_036":1,"q_thpt22_037":0,"q_thpt22_038":0,"q_thpt22_039":1,"q_thpt22_040":1,"q_thpt22_041":1,"q_thpt22_042":0,"q_thpt22_043":1,"q_thpt22_044":1,"q_thpt22_045":0,"q_thpt22_046":1,"q_thpt22_047":1,"q_thpt22_048":1,"q_thpt22_049":0,"q_thpt22_050":1,"q_thithu_hn24_001":1,"q_thithu_hn24_002":0,"q_thithu_hn24_003":1,"q_thithu_hn24_004":0,"q_thithu_hn24_005":1,"q_thithu_hn24_006":0,"q_thithu_hn24_007":2,"q_thithu_hn24_008":0,"q_thithu_hn24_009":0,"q_thithu_hn24_010":0,"q_thithu_hn24_011":2,"q_thithu_hn24_012":1,"q_thithu_hn24_013":0,"q_thithu_hn24_014":0,"q_thithu_hn24_015":1,"q_thithu_hn24_016":1,"q_thithu_hn24_017":2,"q_thithu_hn24_018":0,"q_thithu_hn24_019":0,"q_thithu_hn24_020":1,"q_thithu_hn24_021":0,"q_thithu_hn24_022":0,"q_thithu_hn24_023":0,"q_thithu_hn24_024":0,"q_thithu_hn24_025":0,"q_thithu_hn24_026":0,"q_thithu_hn24_027":0,"q_thithu_hn24_028":0,"q_thithu_hn24_029":0,"q_thithu_hn24_030":0,"q_thithu_hn24_031":0,"q_thithu_hn24_032":0,"q_thithu_hn24_033":0,"q_thithu_hn24_034":0,"q_thithu_hn24_035":0,"q_thithu_hn24_036":0,"q_thithu_hn24_037":0,"q_thithu_hn24_038":0,"q_thithu_hn24_039":0,"q_thithu_hn24_040":0,"q_thithu_hn24_041":0,"q_thithu_hn24_042":0,"q_thithu_hn24_043":0,"q_thithu_hn24_044":0,"q_thithu_hn24_045":0,"q_thithu_hn24_046":0,"q_thithu_hn24_047":0,"q_thithu_hn24_048":0,"q_thithu_hn24_049":0,"q_thithu_hn24_050":0,"q_thithu_hcm24_001":2,"q_thithu_hcm24_002":1,"q_thithu_hcm24_003":1,"q_thithu_hcm24_004":2,"q_thithu_hcm24_005":2,"q_thithu_hcm24_006":1,"q_thithu_hcm24_007":0,"q_thithu_hcm24_008":1,"q_thithu_hcm24_009":0,"q_thithu_hcm24_010":0,"q_thithu_hcm24_011":1,"q_thithu_hcm24_012":1,"q_thithu_hcm24_013":0,"q_thithu_hcm24_014":0,"q_thithu_hcm24_015":2,"q_thithu_hcm24_016":2,"q_thithu_hcm24_017":1,"q_thithu_hcm24_018":1,"q_thithu_hcm24_019":0,"q_thithu_hcm24_020":1,"q_thithu_hcm24_021":0,"q_thithu_hcm24_022":0,"q_thithu_hcm24_023":0,"q_thithu_hcm24_024":0,"q_thithu_hcm24_025":0,"q_thithu_hcm24_026":0,"q_thithu_hcm24_027":0,"q_thithu_hcm24_028":0,"q_thithu_hcm24_029":0,"q_thithu_hcm24_030":0,"q_thithu_hcm24_031":0,"q_thithu_hcm24_032":0,"q_thithu_hcm24_033":0,"q_thithu_hcm24_034":0,"q_thithu_hcm24_035":0,"q_thithu_hcm24_036":0,"q_thithu_hcm24_037":0,"q_thithu_hcm24_038":0,"q_thithu_hcm24_039":0,"q_thithu_hcm24_040":0,"q_thithu_hcm24_041":0,"q_thithu_hcm24_042":0,"q_thithu_hcm24_043":0,"q_thithu_hcm24_044":0,"q_thithu_hcm24_045":0,"q_thithu_hcm24_046":0,"q_thithu_hcm24_047":0,"q_thithu_hcm24_048":0,"q_thithu_hcm24_049":0,"q_thithu_hcm24_050":0,"q_sat_001":0,"q_sat_002":0,"q_sat_003":0,"q_sat_004":0,"q_sat_005":0,"q_sat_006":0,"q_sat_007":0,"q_sat_008":0,"q_sat_009":0,"q_sat_010":0,"q_sat_011":0,"q_sat_012":0,"q_sat_013":0,"q_sat_014":0,"q_sat_015":0,"q_sat_016":0,"q_sat_017":0,"q_sat_018":0,"q_sat_019":0,"q_sat_020":0,"q_gauss_001":0,"q_gauss_002":0,"q_gauss_003":0,"q_gauss_004":0,"q_gauss_005":0,"q_gauss_006":0,"q_gauss_007":0,"q_gauss_008":0,"q_gauss_009":0,"q_gauss_010":0,"q_gauss_011":0,"q_gauss_012":0,"q_gauss_013":0,"q_gauss_014":0,"q_gauss_015":0,"q_gauss_016":0,"q_gauss_017":0,"q_gauss_018":0,"q_gauss_019":0,"q_gauss_020":0,"q_ib_sl_001":0,"q_ib_sl_002":0,"q_ib_sl_003":0,"q_ib_sl_004":0,"q_ib_sl_005":0,"q_ib_sl_006":0,"q_ib_sl_007":0,"q_ib_sl_008":0,"q_ib_sl_009":0,"q_ib_sl_010":0,"q_ib_sl_011":0,"q_ib_sl_012":0,"q_ib_sl_013":0,"q_ib_sl_014":0,"q_ib_sl_015":0,"q_ib_sl_016":0,"q_ib_sl_017":0,"q_ib_sl_018":0,"q_ib_sl_019":0,"q_ib_sl_020":0,"q_ksat_001":0,"q_ksat_002":0,"q_ksat_003":0,"q_ksat_004":0,"q_ksat_005":0,"q_ksat_006":0,"q_ksat_007":0,"q_ksat_008":0,"q_ksat_009":0,"q_ksat_010":0,"q_ksat_011":0,"q_ksat_012":0,"q_ksat_013":0,"q_ksat_014":0,"q_ksat_015":0,"q_ksat_016":0,"q_ksat_017":0,"q_ksat_018":0,"q_ksat_019":0,"q_ksat_020":0,"q_jee_001":0,"q_jee_002":0,"q_jee_003":0,"q_jee_004":0,"q_jee_005":0,"q_jee_006":0,"q_jee_007":0,"q_jee_008":0,"q_jee_009":0,"q_jee_010":0,"q_jee_011":0,"q_jee_012":0,"q_jee_013":0,"q_jee_014":0,"q_jee_015":0,"q_jee_016":0,"q_jee_017":0,"q_jee_018":0,"q_jee_019":0,"q_jee_020":0,"q_sat_021":0,"q_sat_022":0,"q_sat_023":0,"q_sat_024":0,"q_sat_025":0,"q_sat_026":0,"q_sat_027":0,"q_sat_028":0,"q_sat_029":0,"q_sat_030":0,"q_sat_031":0,"q_sat_032":0,"q_sat_033":0,"q_sat_034":0,"q_sat_035":0,"q_sat_036":0,"q_sat_037":0,"q_sat_038":0,"q_sat_039":0,"q_sat_040":0,"q_sat_041":0,"q_sat_042":0,"q_sat_043":0,"q_sat_044":0,"q_gauss_021":0,"q_gauss_022":0,"q_gauss_023":0,"q_gauss_024":0,"q_gauss_025":0,"q_ib_sl_021":0,"q_ib_sl_022":0,"q_ib_sl_023":0,"q_ib_sl_024":0,"q_ib_sl_025":0,"q_ib_sl_026":0,"q_ib_sl_027":0,"q_ib_sl_028":0,"q_ib_sl_029":0,"q_ib_sl_030":0,"q_ksat_021":0,"q_ksat_022":0,"q_ksat_023":0,"q_ksat_024":0,"q_ksat_025":0,"q_ksat_026":0,"q_ksat_027":0,"q_ksat_028":0,"q_ksat_029":0,"q_ksat_030":0,"q_jee_021":0,"q_jee_022":0,"q_jee_023":0,"q_jee_024":0,"q_jee_025":0,"q_jee_026":0,"q_jee_027":0,"q_jee_028":0,"q_jee_029":0,"q_jee_030":0,"q_mx01_001":3,"q_mx01_002":3,"q_mx01_003":1,"q_mx01_004":0,"q_mx01_005":1,"q_mx01_006":3,"q_mx01_007":1,"q_mx01_008":2,"q_mx01_009":0,"q_mx01_010":2,"q_mx01_011":1,"q_mx01_012":3,"q_mx01_013":3,"q_mx01_014":3,"q_mx01_015":0,"q_mx01_016":0,"q_mx01_017":3,"q_mx01_018":1,"q_mx01_019":0,"q_mx01_020":0,"q_mx01_021":1,"q_mx01_022":3,"q_mx01_023":1,"q_mx01_024":1,"q_mx01_025":3,"q_mx01_026":1,"q_mx01_027":0,"q_mx01_028":0,"q_mx01_029":1,"q_mx01_030":1,"q_mx01_031":2,"q_mx01_032":3,"q_mx01_033":0,"q_mx01_034":2,"q_mx01_035":3,"q_mx01_036":2,"q_mx01_037":2,"q_mx01_038":2,"q_mx01_039":3,"q_mx01_040":3,"q_mx01_041":1,"q_mx01_042":1,"q_mx01_043":0,"q_mx01_044":3,"q_mx01_045":0,"q_mx01_046":0,"q_mx01_047":2,"q_mx01_048":3,"q_mx01_049":0,"q_mx01_050":1,"q_vj01_01":1,"q_vj01_02":2,"q_vj01_03":1,"q_vj01_04":0,"q_vj01_05":3,"q_vj01_06":0,"q_vj01_07":2,"q_vj01_08":3,"q_vj02_01":2,"q_vj02_02":0,"q_vj02_03":3,"q_vj02_04":2,"q_vj02_05":1,"q_vj02_06":0,"q_vj02_07":1,"q_vj02_08":2,"q_vj03_01":3,"q_vj03_02":0,"q_vj03_03":3,"q_vj03_04":1,"q_vj03_05":0,"q_vj03_06":2,"q_vj03_07":1,"q_vj03_08":2,"q_vj04_01":1,"q_vj04_02":2,"q_vj04_03":0,"q_vj04_04":3,"q_vj04_05":0,"q_vj04_06":3,"q_vj04_07":2,"q_vj04_08":1,"q_vj05_01":2,"q_vj05_02":3,"q_vj05_03":0,"q_vj05_04":3,"q_vj05_05":1,"q_vj05_06":0,"q_vj05_07":3,"q_vj05_08":1,"q_lgh_173342_01":3,"q_lgh_173342_02":1,"q_lgh_173342_03":1,"q_lgh_173342_04":2,"q_lgh_173342_05":3,"q_lgh_173342_06":1,"q_lgh_173342_07":1,"q_lgh_173342_08":0,"q_lgh_173342_09":0,"q_lgh_173342_10":2,"q_lgh_173342_11":3,"q_lgh_173342_12":3,"q_lgh_173478_01":0,"q_lgh_173478_02":3,"q_lgh_173478_03":1,"q_lgh_173478_04":1,"q_lgh_173478_05":2,"q_lgh_173478_06":3,"q_lgh_173478_07":3,"q_lgh_173478_08":0,"q_lgh_173478_09":3,"q_lgh_173478_10":1,"q_lgh_173478_11":3,"q_lgh_173478_12":3,"q_lgh_173753_01":1,"q_lgh_173753_02":3,"q_lgh_173753_03":0,"q_lgh_173753_04":0,"q_lgh_173753_05":1,"q_lgh_173753_06":3,"q_lgh_173753_07":3,"q_lgh_173753_08":0,"q_lgh_173753_09":1,"q_lgh_173753_10":1,"q_lgh_173753_11":1,"q_lgh_173753_12":1,"q_lgh_173871_01":3,"q_lgh_173871_02":2,"q_lgh_173871_03":1,"q_lgh_173871_04":0,"q_lgh_173871_05":3,"q_lgh_173871_06":1,"q_lgh_173871_07":2,"q_lgh_173871_08":0,"q_lgh_173871_09":3,"q_lgh_173871_10":2,"q_lgh_173871_11":3,"q_lgh_173871_12":0,"q_lgh_173945_01":2,"q_lgh_173945_02":1,"q_lgh_173945_03":2,"q_lgh_173945_04":2,"q_lgh_173945_05":3,"q_lgh_173945_06":3,"q_lgh_173945_07":2,"q_lgh_173945_08":2,"q_lgh_173945_09":3,"q_lgh_173945_10":2,"q_lgh_173945_11":1,"q_lgh_173945_12":3,"q_lgh_180179_01":2,"q_lgh_180179_02":0,"q_lgh_180179_03":3,"q_lgh_180179_04":3,"q_lgh_180179_05":2,"q_lgh_180179_06":1,"q_lgh_180840_01":0,"q_lgh_180840_02":1,"q_lgh_180840_03":0,"q_lgh_180840_04":0,"q_lgh_180840_05":2,"q_lgh_180840_06":1,"q_lgh_180918_01":0,"q_lgh_180918_02":2,"q_lgh_180918_03":3,"q_lgh_180918_04":2,"q_lgh_180918_05":1,"q_lgh_180918_06":2,"q_lgh_180978_01":2,"q_lgh_180978_02":0,"q_lgh_180978_03":1,"q_lgh_180978_04":3,"q_lgh_180978_05":2,"q_lgh_180978_06":2,"q_lgh_181040_01":3,"q_lgh_181040_02":2,"q_lgh_181040_03":2,"q_lgh_181040_04":3,"q_lgh_181040_05":1,"q_lgh_181040_06":1,"q_lgh_177656_01":0,"q_lgh_177656_02":3,"q_lgh_177656_03":1,"q_lgh_177656_04":2,"q_lgh_177656_05":2,"q_lgh_177656_06":2,"q_lgh_177656_07":1,"q_lgh_177656_08":3,"q_lgh_177656_09":0,"q_lgh_177656_10":1,"q_lgh_177656_11":3,"q_lgh_177656_12":3,"q_lgh_177657_01":0,"q_lgh_177657_02":0,"q_lgh_177657_03":3,"q_lgh_177657_04":2,"q_lgh_177657_05":2,"q_lgh_177657_06":0,"q_lgh_177657_07":3,"q_lgh_177657_08":1,"q_lgh_177657_09":0,"q_lgh_177657_10":3,"q_lgh_177657_11":1,"q_lgh_177657_12":3,"q_lgh_177661_01":1,"q_lgh_177661_02":0,"q_lgh_177661_03":2,"q_lgh_177661_04":0,"q_lgh_177661_05":1,"q_lgh_177661_06":2,"q_lgh_177661_07":3,"q_lgh_177661_08":1,"q_lgh_177661_10":0,"q_lgh_177661_11":3,"q_lgh_177661_12":2,"q_lgh_177714_01":2,"q_lgh_177714_02":2,"q_lgh_177714_03":1,"q_lgh_177714_04":3,"q_lgh_177714_05":1,"q_lgh_177714_06":1,"q_lgh_177714_07":2,"q_lgh_177714_08":2,"q_lgh_177714_09":1,"q_lgh_177714_10":2,"q_lgh_177714_11":0,"q_lgh_177714_12":0,"q_lgh_177717_01":3,"q_lgh_177717_02":0,"q_lgh_177717_03":2,"q_lgh_177717_04":1,"q_lgh_177717_05":2,"q_lgh_177717_06":3,"q_lgh_177717_07":2,"q_lgh_177717_08":2,"q_lgh_177717_09":3,"q_lgh_177717_10":0,"q_lgh_177717_11":1,"q_lgh_177717_12":3,"q_lgh_182201_01":2,"q_lgh_182201_02":2,"q_lgh_182201_03":2,"q_lgh_182201_04":2,"q_lgh_182201_05":3,"q_lgh_182201_06":3,"q_lgh_182201_07":1,"q_lgh_182201_08":0,"q_lgh_182201_09":0,"q_lgh_182201_10":2,"q_lgh_182201_11":3,"q_lgh_182201_12":1,"q_lgh_182313_01":1,"q_lgh_182313_02":1,"q_lgh_182313_03":2,"q_lgh_182313_04":2,"q_lgh_182313_05":2,"q_lgh_182313_06":0,"q_lgh_182313_07":3,"q_lgh_182313_08":1,"q_lgh_182313_09":3,"q_lgh_182313_10":0,"q_lgh_182313_11":2,"q_lgh_182313_12":1,"q_lgh_182339_01":0,"q_lgh_182339_02":3,"q_lgh_182339_03":1,"q_lgh_182339_04":2,"q_lgh_182339_05":3,"q_lgh_182339_06":2,"q_lgh_182339_07":2,"q_lgh_182339_08":3,"q_lgh_182339_09":3,"q_lgh_182339_10":1,"q_lgh_182339_11":0,"q_lgh_182339_12":2,"q_lgh_182635_01":1,"q_lgh_182635_02":2,"q_lgh_182635_03":2,"q_lgh_182635_04":3,"q_lgh_182635_05":2,"q_lgh_182635_06":2,"q_lgh_182635_07":1,"q_lgh_182635_09":2,"q_lgh_182635_10":3,"q_lgh_182635_11":1,"q_lgh_182635_12":2,"q_lgh_182707_01":0,"q_lgh_182707_02":0,"q_lgh_182707_03":1,"q_lgh_182707_04":0,"q_lgh_182707_05":1,"q_lgh_182707_06":3,"q_lgh_182707_07":3,"q_lgh_182707_08":0,"q_lgh_182707_09":2,"q_lgh_182707_10":0,"q_lgh_182707_11":1,"q_lgh_182707_12":0,"q_bece22_01":1,"q_bece22_02":0,"q_bece22_03":2,"q_bece22_04":3,"q_bece22_05":1,"q_bece22_06":1,"q_bece22_07":1,"q_bece22_08":2,"q_bece22_09":3,"q_bece22_10":1,"q_bece22_11":3,"q_bece22_12":1,"q_bece22_13":0,"q_bece22_14":0,"q_bece22_15":1,"q_bece22_16":1,"q_bece22_17":2,"q_bece22_18":2,"q_bece22_19":3,"q_bece22_20":0,"q_bece22_21":1,"q_bece22_22":3,"q_bece22_23":0,"q_bece22_24":3,"q_bece22_25":2,"q_bece21_01":0,"q_bece21_02":0,"q_bece21_03":2,"q_bece21_04":2,"q_bece21_05":2,"q_bece21_06":0,"q_bece21_07":2,"q_bece21_08":2,"q_bece21_09":0,"q_bece21_10":2,"q_bece21_11":2,"q_bece21_12":3,"q_bece21_13":0,"q_bece21_14":2,"q_bece21_15":2,"q_bece21_16":1,"q_bece21_17":1,"q_bece21_18":2,"q_bece21_19":1,"q_bece21_20":2,"q_bece21_21":0,"q_bece21_22":3,"q_bece21_23":1,"q_bece21_24":0,"q_bece21_25":0,"q_bece24_01":3,"q_bece24_02":1,"q_bece24_03":2,"q_bece24_04":1,"q_bece24_05":0,"q_bece24_06":0,"q_bece24_07":0,"q_bece24_08":0,"q_bece24_09":1,"q_bece24_10":3,"q_bece24_11":1,"q_bece24_12":2,"q_bece24_13":1,"q_bece24_14":3,"q_bece24_15":0,"q_bece24_16":0,"q_bece24_17":0,"q_bece24_18":1,"q_bece24_19":0,"q_bece24_20":2,"q_bece24_21":2,"q_bece24_22":3,"q_bece24_23":2,"q_bece24_24":1,"q_bece24_25":2,"q_cbse24p1_01":3,"q_cbse24p1_02":1,"q_cbse24p1_03":0,"q_cbse24p1_04":0,"q_cbse24p1_05":0,"q_cbse24p1_06":2,"q_cbse24p1_07":1,"q_cbse24p1_08":0,"q_cbse24p1_09":0,"q_cbse24p1_10":3,"q_cbse24p1_11":1,"q_cbse24p1_12":1,"q_cbse24p1_13":1,"q_cbse24p1_14":3,"q_cbse24p1_15":1,"q_cbse24p1_16":1,"q_cbse24p1_17":0,"q_cbse24p1_18":1,"q_cbse24p1_19":2,"q_cbse24p1_20":3,"q_cbse24p1_21":0,"q_cbse24p1_22":1,"q_cbse24p1_23":0,"q_cbse24p1_24":0,"q_cbse24p1_25":0,"q_cbse24p2_01":1,"q_cbse24p2_02":0,"q_cbse24p2_03":2,"q_cbse24p2_04":1,"q_cbse24p2_05":0,"q_cbse24p2_06":0,"q_cbse24p2_07":1,"q_cbse24p2_08":1,"q_cbse24p2_09":2,"q_cbse24p2_10":2,"q_cbse24p2_11":1,"q_cbse24p2_12":0,"q_cbse24p2_13":2,"q_cbse24p2_14":0,"q_cbse24p2_15":0,"q_cbse24p2_16":3,"q_cbse24p2_17":2,"q_cbse24p2_18":2,"q_cbse24p2_19":1,"q_cbse24p2_20":1,"q_cbse24p2_21":3,"q_cbse24p2_22":0,"q_cbse24p2_23":1,"q_cbse24p2_24":0,"q_cbse24p2_25":0,"q_bece22_26":0,"q_bece22_27":1,"q_bece22_28":1,"q_bece22_29":0,"q_bece22_30":2,"q_bece22_31":1,"q_bece22_32":0,"q_bece22_33":2,"q_bece22_34":1,"q_bece22_35":0,"q_bece22_36":1,"q_bece22_37":1,"q_bece22_38":1,"q_bece22_39":1,"q_bece21_26":1,"q_bece21_27":2,"q_bece21_28":0,"q_bece21_29":0,"q_bece21_30":0,"q_bece21_31":0,"q_bece21_32":0,"q_bece21_33":0,"q_bece21_34":0,"q_bece21_35":0,"q_bece21_36":3,"q_bece21_37":1,"q_bece21_38":0,"q_bece21_39":1,"q_bece24_26":2,"q_bece24_27":0,"q_bece24_28":1,"q_bece24_29":1,"q_bece24_30":2,"q_bece24_31":2,"q_bece24_32":1,"q_bece24_33":3,"q_bece24_34":2,"q_bece24_35":0,"q_bece24_36":1,"q_bece24_37":1,"q_bece24_38":3,"q_bece24_39":3,"q_cbse24p1_26":2,"q_cbse24p1_27":0,"q_cbse24p1_28":0,"q_cbse24p1_29":1,"q_cbse24p1_30":1,"q_cbse24p1_31":3,"q_cbse24p1_32":2,"q_cbse24p1_33":2,"q_cbse24p1_34":0,"q_cbse24p1_35":1,"q_cbse24p1_36":0,"q_cbse24p1_37":1,"q_cbse24p1_38":0,"q_cbse24p1_39":1,"q_cbse24p1_40":0,"q_cbse24p2_26":0,"q_cbse24p2_27":1,"q_cbse24p2_28":1,"q_cbse24p2_29":1,"q_cbse24p2_30":2,"q_cbse24p2_31":1,"q_cbse24p2_32":1,"q_cbse24p2_33":3,"q_cbse24p2_34":1,"q_cbse24p2_35":2,"q_cbse24p2_36":2,"q_cbse24p2_37":0,"q_cbse24p2_38":0,"q_cbse24p2_39":1,"q_cbse24p2_40":0}

backend/app/db.py

@@ -0,0 +1,214 @@
+"""asyncpg-compatible wrapper around aiosqlite for local SQLite storage.
+
+Drop-in replacement for the asyncpg connection pool: same acquire(), fetchrow(),
+fetch(), fetchval(), execute(), and transaction() API, so pg_db.py / analytics.py /
+sanitizer.py require zero changes.
+
+SQL translation handled automatically:
+  $N placeholders  → ?
+  = ANY($N)        → IN (?,?,?)  (array expansion)
+  ::type casts     → stripped
+  NOW()            → datetime('now')
+  list params      → JSON-serialised (for embedding storage)
+
+Architecture note:
+  A single persistent aiosqlite connection is shared across all callers.  An
+  asyncio.Lock serialises every acquire() so only one coroutine touches the
+  SQLite file at a time.  This eliminates the concurrent-writer corruption that
+  WAL mode's shared-memory coordination (-shm/-wal files) causes on
+  network/container filesystems (NFS, Docker overlays, HuggingFace Spaces /data).
+"""
+import asyncio
+import json
+import logging
+import re
+import sqlite3
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, AsyncGenerator, Optional
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+
+class Row(dict):
+    """Dict that also supports positional (integer) access like asyncpg Record."""
+
+    def __getitem__(self, key: Any) -> Any:
+        if isinstance(key, int):
+            return list(self.values())[key]
+        return super().__getitem__(key)
+
+
+def _translate(query: str, params: tuple) -> tuple[str, list]:
+    """Translate PostgreSQL query + params to SQLite equivalents."""
+    # Detect which $N positions are used by ANY($N) (0-based)
+    any_positions: set[int] = set()
+    for m in re.finditer(r"=\s*ANY\(\$(\d+)\)", query, re.IGNORECASE):
+        any_positions.add(int(m.group(1)) - 1)
+
+    # Expand = ANY($N) → IN (?,?,?)
+    def _expand_any(m: re.Match) -> str:
+        idx = int(m.group(1)) - 1
+        arr = list(params[idx]) if params[idx] else []
+        return f"IN ({','.join(['?'] * len(arr))})" if arr else "IN (NULL)"
+
+    query = re.sub(r"=\s*ANY\(\$(\d+)\)", _expand_any, query, flags=re.IGNORECASE)
+
+    # Strip PostgreSQL type casts: ::jsonb, ::timestamptz, ::text[], ::float, etc.
+    query = re.sub(r"::[a-zA-Z_][\w\[\]]*", "", query)
+
+    # Replace NOW() with SQLite equivalent
+    query = re.sub(r"\bNOW\(\)", "datetime('now')", query, flags=re.IGNORECASE)
+
+    # Build flat params, expanding ANY arrays and serialising lists→JSON
+    new_params: list = []
+    for i, p in enumerate(params):
+        if i in any_positions:
+            new_params.extend(list(p) if p else [])
+        elif isinstance(p, list):
+            new_params.append(json.dumps(p))
+        else:
+            new_params.append(p)
+
+    # Replace remaining $N placeholders with ?
+    query = re.sub(r"\$\d+", "?", query)
+
+    return query, new_params
+
+
+class _Connection:
+    def __init__(self, conn: aiosqlite.Connection) -> None:
+        self._conn = conn
+        self._in_transaction = False
+
+    async def fetchrow(self, query: str, *args) -> Optional[Row]:
+        q, params = _translate(query, args)
+        cur = await self._conn.execute(q, params)
+        row = await cur.fetchone()
+        # Commit after fetch so INSERT … RETURNING rows are both readable and persisted.
+        if not self._in_transaction:
+            await self._conn.commit()
+        if row is None or cur.description is None:
+            return None
+        cols = [d[0] for d in cur.description]
+        return Row(zip(cols, row))
+
+    async def fetch(self, query: str, *args) -> list[Row]:
+        q, params = _translate(query, args)
+        cur = await self._conn.execute(q, params)
+        rows = await cur.fetchall()
+        if not self._in_transaction:
+            await self._conn.commit()
+        if cur.description is None:
+            return []
+        cols = [d[0] for d in cur.description]
+        return [Row(zip(cols, r)) for r in rows]
+
+    async def fetchval(self, query: str, *args) -> Any:
+        q, params = _translate(query, args)
+        cur = await self._conn.execute(q, params)
+        row = await cur.fetchone()
+        if not self._in_transaction:
+            await self._conn.commit()
+        return row[0] if row else None
+
+    async def execute(self, query: str, *args) -> str:
+        q, params = _translate(query, args)
+        cur = await self._conn.execute(q, params)
+        if not self._in_transaction:
+            await self._conn.commit()
+        return f"UPDATE {cur.rowcount}"
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncGenerator[None, None]:
+        self._in_transaction = True
+        try:
+            yield
+            await self._conn.commit()
+        except BaseException:
+            await self._conn.rollback()
+            raise
+        finally:
+            self._in_transaction = False
+
+
+class AsyncSQLitePool:
+    """Single-connection asyncpg-compatible pool backed by a local SQLite file.
+
+    One persistent aiosqlite connection is shared by all callers.  An asyncio.Lock
+    ensures only one coroutine executes against the connection at a time, which is
+    both sufficient (single uvicorn process) and necessary (prevents WAL-mode
+    shared-memory corruption on container/NFS filesystems).
+    """
+
+    def __init__(self, db_path: str) -> None:
+        self._path = db_path
+        self._conn: Optional[aiosqlite.Connection] = None
+        self._lock: asyncio.Lock = asyncio.Lock()
+        Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+
+    async def initialize(self) -> None:
+        """Open the persistent connection; auto-recover if the DB file is corrupted."""
+        try:
+            conn = await aiosqlite.connect(self._path)
+            await conn.execute("PRAGMA foreign_keys = ON")
+            await conn.execute("PRAGMA cache_size = -64000")   # 64 MB in-process page cache
+            await conn.execute("PRAGMA busy_timeout = 5000")   # queue 5 s before failing
+            cur = await conn.execute("PRAGMA integrity_check")
+            row = await cur.fetchone()
+            if row and row[0] != "ok":
+                await conn.close()
+                raise sqlite3.DatabaseError(f"integrity_check: {row[0]}")
+            await conn.commit()
+            self._conn = conn
+        except (sqlite3.DatabaseError, Exception) as exc:
+            logger.warning("DB at %s is corrupt (%s) — wiping and recreating", self._path, exc)
+            if self._conn is not None:
+                try:
+                    await self._conn.close()
+                except Exception:
+                    pass
+                self._conn = None
+            path = Path(self._path)
+            for suffix in ("", "-wal", "-shm"):
+                candidate = Path(str(path) + suffix)
+                if candidate.exists():
+                    candidate.unlink()
+            conn = await aiosqlite.connect(self._path)
+            await conn.execute("PRAGMA foreign_keys = ON")
+            await conn.execute("PRAGMA cache_size = -64000")
+            await conn.execute("PRAGMA busy_timeout = 5000")
+            await conn.commit()
+            self._conn = conn
+            logger.info("Fresh DB created at %s", self._path)
+
+    @asynccontextmanager
+    async def acquire(self) -> AsyncGenerator[_Connection, None]:
+        async with self._lock:
+            yield _Connection(self._conn)
+
+    # Shortcut methods (asyncpg pools expose these directly)
+
+    async def fetchrow(self, query: str, *args) -> Optional[Row]:
+        async with self.acquire() as conn:
+            return await conn.fetchrow(query, *args)
+
+    async def fetch(self, query: str, *args) -> list[Row]:
+        async with self.acquire() as conn:
+            return await conn.fetch(query, *args)
+
+    async def fetchval(self, query: str, *args) -> Any:
+        async with self.acquire() as conn:
+            return await conn.fetchval(query, *args)
+
+    async def execute(self, query: str, *args) -> str:
+        async with self.acquire() as conn:
+            return await conn.execute(query, *args)
+
+    async def close(self) -> None:
+        async with self._lock:
+            if self._conn is not None:
+                await self._conn.close()
+                self._conn = None

backend/app/dependencies.py

@@ -0,0 +1,108 @@
+import time
+from functools import lru_cache
+from openai import AsyncOpenAI
+from fastapi import Depends, HTTPException, Request, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from pydantic import BaseModel
+import jwt
+from cachetools import TTLCache
+
+from app.config import get_settings
+from app.auth import decode_jwt
+
+# Cache account status (suspended/locked/deactivated) for 30 s per user.
+_account_status_cache: TTLCache = TTLCache(maxsize=500, ttl=30)
+
+_last_seen_flush: dict[int, float] = {}
+_SEEN_DEBOUNCE = 60  # seconds
+
+
+def invalidate_account_cache(user_id: int) -> None:
+    _account_status_cache.pop(user_id, None)
+
+
+@lru_cache
+def get_ai_client() -> AsyncOpenAI:
+    settings = get_settings()
+    router_root = settings.anthropic_base_url.rstrip("/")
+    return AsyncOpenAI(
+        api_key=settings.anthropic_auth_token,
+        base_url=f"{router_root}/v2",
+    )
+
+
+# Backward-compat alias
+get_anthropic_client = get_ai_client
+
+
+class CurrentUser(BaseModel):
+    user_id: int
+    email: str
+
+
+_bearer = HTTPBearer(auto_error=False)
+
+
+async def get_current_user(
+    request: Request,
+    credentials: HTTPAuthorizationCredentials | None = Depends(_bearer),
+) -> CurrentUser:
+    if not credentials:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Not authenticated")
+    try:
+        payload = decode_jwt(credentials.credentials)
+    except jwt.ExpiredSignatureError:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Token expired")
+    except jwt.InvalidTokenError:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
+
+    user = CurrentUser(user_id=int(payload["sub"]), email=payload.get("email", ""))
+
+    pool = getattr(request.app.state, "pool", None)
+    if not pool:
+        raise HTTPException(status_code=503, detail="Service unavailable")
+    ip = request.client.host if request.client else None
+
+    cached = _account_status_cache.get(user.user_id)
+    if cached is None:
+        row = await pool.fetchrow(
+            "SELECT is_suspended, suspension_reason, is_locked, lock_reason, is_deactivated FROM users WHERE id = ?",
+            user.user_id,
+        )
+        cached = {
+            "suspended": bool(row and row["is_suspended"]),
+            "suspension_reason": (row["suspension_reason"] or "") if row else "",
+            "locked": bool(row and row["is_locked"]),
+            "lock_reason": (row["lock_reason"] or "") if row else "",
+            "deactivated": bool(row and row["is_deactivated"]),
+        }
+        _account_status_cache[user.user_id] = cached
+
+    if cached["locked"]:
+        raise HTTPException(
+            status_code=403,
+            detail={"code": "account_locked", "reason": cached["lock_reason"]},
+        )
+    if cached["suspended"]:
+        raise HTTPException(
+            status_code=403,
+            detail={"code": "account_suspended", "reason": cached["suspension_reason"]},
+        )
+    if cached["deactivated"]:
+        raise HTTPException(
+            status_code=403,
+            detail={"code": "account_deactivated"},
+        )
+    if ip:
+        now_mono = time.monotonic()
+        needs_seen = (now_mono - _last_seen_flush.get(user.user_id, 0)) >= _SEEN_DEBOUNCE
+        if needs_seen:
+            _last_seen_flush[user.user_id] = now_mono
+            await pool.execute(
+                "UPDATE users SET last_ip = ?, last_seen_at = datetime('now') WHERE id = ?",
+                ip, user.user_id,
+            )
+        else:
+            await pool.execute("UPDATE users SET last_ip = ? WHERE id = ?", ip, user.user_id)
+
+    return user

backend/app/math_wiki/admin_router.py

@@ -0,0 +1,419 @@
+import json
+import logging
+from datetime import datetime, timezone
+from fastapi import APIRouter, Depends, HTTPException, Header, Query, Request
+from pydantic import BaseModel
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.dependencies import get_ai_client
+from app.math_wiki.storage import pg_db
+from app.math_wiki.storage.analytics import get_retrieval_effectiveness, get_unit_usage_stats
+from app.math_wiki.schemas import WikiUnit, StagedWikiUnit
+import asyncio
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/admin", tags=["admin"])
+
+# ── Crawl job state (in-process singleton, one crawl at a time) ───────────────
+
+_crawl: dict = {
+    "running": False,
+    "started_at": None,
+    "finished_at": None,
+    "topics": [],
+    "sources": [],
+    "dry_run": False,
+    "stats": {},
+    "current_topic": None,
+    "error": None,
+}
+
+
+def _check_admin_key(x_admin_key: str = Header(...)):
+    settings = get_settings()
+    if not settings.admin_key or x_admin_key != settings.admin_key:
+        raise HTTPException(status_code=401, detail="Invalid admin key")
+
+
+def _get_pool(request: Request):
+    return request.app.state.pool
+
+
+# ── Wiki Units ────────────────────────────────────────────────────────────────
+
+@router.get("/units")
+async def admin_list_units(
+    topic: str | None = Query(None),
+    source: str | None = Query(None),
+    include_deleted: bool = Query(False),
+    limit: int = Query(50, ge=1, le=200),
+    offset: int = Query(0, ge=0),
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    units = await pg_db.list_wiki_units_admin(
+        pool, topic=topic, source=source,
+        include_deleted=include_deleted,
+        limit=limit, offset=offset,
+    )
+    return {"units": units, "count": len(units)}
+
+
+@router.get("/staged-units", response_model=list[StagedWikiUnit])
+async def admin_list_staged_units(
+    status: str = Query("pending"),
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    return await pg_db.get_staged_wiki_units(pool, status=status)
+
+
+@router.post("/staged-units/{unit_id}/approve")
+async def admin_approve_staged_unit(
+    unit_id: str,
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    try:
+        approved_unit = await pg_db.approve_staged_wiki_unit(pool, unit_id)
+        if approved_unit:
+            return {"status": "approved", "id": unit_id}
+        raise HTTPException(status_code=404, detail="Staged unit not found")
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/staged-units/{unit_id}")
+async def admin_delete_staged_unit(
+    unit_id: str,
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    try:
+        await pg_db.delete_staged_wiki_unit(pool, unit_id)
+        return {"status": "deleted", "id": unit_id}
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.get("/units/{unit_id}")
+async def admin_get_unit(
+    unit_id: str,
+    include_history: bool = Query(False),
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    result = await pg_db.get_wiki_unit_with_history(pool, unit_id)
+    if not result:
+        raise HTTPException(status_code=404, detail="Unit not found")
+    if not include_history:
+        result.pop("history", None)
+    return result
+
+
+class UnitUpdateRequest(BaseModel):
+    content: str
+    editor: str = "admin"
+    reason: str | None = None
+
+
+@router.put("/units/{unit_id}")
+async def admin_update_unit(
+    unit_id: str,
+    req: UnitUpdateRequest,
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    data = await pg_db.get_wiki_unit_with_history(pool, unit_id)
+    if not data:
+        raise HTTPException(status_code=404, detail="Unit not found")
+    row = data["unit"]
+    updated = WikiUnit(
+        id=row["id"],
+        type=row["type"],
+        topic=row["topic"],
+        subtopic=row["subtopic"],
+        content=req.content,
+        problem_ids=json.loads(row["problem_ids"]) if isinstance(row["problem_ids"], str) else row["problem_ids"],
+    )
+    await pg_db.upsert_wiki_unit(pool, updated, source=row["source"], editor=req.editor, reason=req.reason)
+    return {"status": "updated", "id": unit_id}
+
+
+@router.delete("/units/{unit_id}")
+async def admin_delete_unit(
+    unit_id: str,
+    editor: str = Query("admin"),
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    ok = await pg_db.soft_delete_wiki_unit(pool, unit_id, editor=editor)
+    if not ok:
+        raise HTTPException(status_code=404, detail="Unit not found")
+    return {"status": "deleted", "id": unit_id}
+
+
+@router.post("/units/{unit_id}/restore")
+async def admin_restore_unit(
+    unit_id: str,
+    version: int | None = Query(None),
+    editor: str = Query("admin"),
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    ok = await pg_db.restore_wiki_unit(pool, unit_id, version=version, editor=editor)
+    if not ok:
+        raise HTTPException(status_code=404, detail="Unit or version not found")
+    return {"status": "restored", "id": unit_id}
+
+
+# ── Feedback ──────────────────────────────────────────────────────────────────
+
+@router.get("/feedback")
+async def admin_list_feedback(
+    unresolved_only: bool = Query(True),
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    rows = await pg_db.list_feedback(pool, unresolved_only=unresolved_only)
+    return {"feedback": rows, "count": len(rows)}
+
+
+@router.post("/feedback/{feedback_id}/resolve")
+async def admin_resolve_feedback(
+    feedback_id: int,
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    ok = await pg_db.resolve_feedback(pool, feedback_id)
+    if not ok:
+        raise HTTPException(status_code=404, detail="Feedback not found")
+    return {"status": "resolved", "id": feedback_id}
+
+
+# ── Flagged solutions ─────────────────────────────────────────────────────────
+
+@router.get("/flagged")
+async def admin_list_flagged(
+    unreviewed_only: bool = Query(True),
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    rows = await pg_db.get_flagged_solutions(pool, unreviewed_only=unreviewed_only)
+    return {"flagged": rows, "count": len(rows)}
+
+
+# ── Drafts ────────────────────────────────────────────────────────────────────
+
+@router.get("/drafts")
+async def admin_list_drafts(
+    status: str = Query("pending"),
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    rows = await pg_db.list_drafts(pool, status=status)
+    return {"drafts": rows, "count": len(rows)}
+
+
+class DraftReviewRequest(BaseModel):
+    decision: str  # approve | reject | edit
+    reviewer: str = "admin"
+    edits: list[dict] | None = None
+
+
+@router.post("/drafts/{draft_id}/review")
+async def admin_review_draft(
+    draft_id: str,
+    req: DraftReviewRequest,
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    try:
+        result = await pg_db.review_draft(
+            pool,
+            draft_id=draft_id,
+            decision=req.decision,
+            reviewer=req.reviewer,
+            edits=req.edits,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    return result
+
+
+# ── Source ingest → draft ─────────────────────────────────────────────────────
+
+class IngestSourceRequest(BaseModel):
+    text: str
+    source_url: str | None = None
+    topic_hint: str | None = None
+
+
+@router.post("/ingest/source")
+async def admin_ingest_source(
+    req: IngestSourceRequest,
+    client: AsyncOpenAI = Depends(get_ai_client),
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    from app.math_wiki.agents.concept_ingest import concept_ingest
+    try:
+        output = await concept_ingest(client, req.text, pool=pool)
+    except Exception as exc:
+        raise HTTPException(status_code=502, detail=f"AI ingest failed: {exc}")
+
+    draft_id = await pg_db.create_draft(
+        pool,
+        source_text=req.text,
+        source_url=req.source_url,
+        topic_hint=req.topic_hint,
+        proposed_units=output.wiki_units if hasattr(output, "wiki_units") else [],
+    )
+    return {
+        "draft_id": draft_id,
+        "proposed_unit_count": len(output.wiki_units) if hasattr(output, "wiki_units") else 0,
+    }
+
+
+# ── Analytics ─────────────────────────────────────────────────────────────────
+
+@router.get("/analytics")
+async def admin_analytics(
+    days: int = Query(30, ge=1, le=365),
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    return await get_retrieval_effectiveness(pool, days=days)
+
+
+@router.get("/analytics/units/{unit_id}")
+async def admin_unit_analytics(
+    unit_id: str,
+    days: int = Query(30, ge=1, le=365),
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    all_stats = await get_unit_usage_stats(pool, days=days)
+    unit_stats = next((s for s in all_stats if s["unit_id"] == unit_id), None)
+    if not unit_stats:
+        return {"unit_id": unit_id, "times_used": 0, "message": "no data"}
+    return unit_stats
+
+
+# ── Crawl trigger ─────────────────────────────────────────────────────────────
+
+class CrawlRequest(BaseModel):
+    gap_threshold: int = 50          # crawl topics with fewer units than this
+    sources: list[str] = ["aops", "pauls", "generic"]
+    dry_run: bool = False
+
+
+async def _run_crawl(client, pool, topics: list[str], sources: list[str], dry_run: bool) -> None:
+    from crawl.runner import crawl_and_ingest
+
+    _crawl["current_topic"] = None
+    combined: dict = {
+        "topics": len(topics),
+        "pages_fetched": 0,
+        "chunks_sent": 0,
+        "wiki_units_added": 0,
+        "skipped_seen": 0,
+        "errors": 0,
+    }
+    try:
+        for topic in topics:
+            _crawl["current_topic"] = topic
+            stats = await crawl_and_ingest(
+                client, topics=[topic], sources=sources, dry_run=dry_run, pool=pool
+            )
+            for k in ("pages_fetched", "chunks_sent", "wiki_units_added", "skipped_seen", "errors"):
+                combined[k] = combined.get(k, 0) + stats.get(k, 0)
+            _crawl["stats"] = dict(combined)
+            logger.info("crawl [%s]: %s", topic, stats)
+            await asyncio.sleep(3)   # inter-topic pause
+    except Exception as exc:
+        _crawl["error"] = str(exc)
+        logger.error("admin crawl failed: %s", exc)
+    finally:
+        _crawl["running"] = False
+        _crawl["finished_at"] = datetime.now(timezone.utc).isoformat()
+        _crawl["current_topic"] = None
+        _crawl["stats"] = dict(combined)
+
+
+@router.post("/crawl")
+async def admin_trigger_crawl(
+    req: CrawlRequest,
+    request: Request,
+    client: AsyncOpenAI = Depends(get_ai_client),
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    if _crawl["running"]:
+        return {
+            "status": "already_running",
+            "started_at": _crawl["started_at"],
+            "current_topic": _crawl["current_topic"],
+        }
+
+    from app.math_wiki.taxonomy import CANONICAL_TOPICS
+
+    topic_counts = await pg_db.count_wiki_units_by_topic(pool)
+    gap_topics = [
+        t for t in CANONICAL_TOPICS
+        if topic_counts.get(t, 0) < req.gap_threshold
+    ]
+
+    if not gap_topics:
+        return {"status": "no_gaps", "message": f"All topics have ≥ {req.gap_threshold} units"}
+
+    _crawl.update({
+        "running": True,
+        "started_at": datetime.now(timezone.utc).isoformat(),
+        "finished_at": None,
+        "topics": gap_topics,
+        "sources": req.sources,
+        "dry_run": req.dry_run,
+        "stats": {},
+        "current_topic": None,
+        "error": None,
+    })
+
+    asyncio.ensure_future(_run_crawl(client, pool, gap_topics, req.sources, req.dry_run))
+
+    return {
+        "status": "started",
+        "topics": gap_topics,
+        "gap_threshold": req.gap_threshold,
+        "sources": req.sources,
+        "dry_run": req.dry_run,
+    }
+
+
+@router.get("/crawl/status")
+async def admin_crawl_status(_: None = Depends(_check_admin_key)):
+    return {
+        "running": _crawl["running"],
+        "started_at": _crawl["started_at"],
+        "finished_at": _crawl["finished_at"],
+        "topics_queued": _crawl["topics"],
+        "current_topic": _crawl["current_topic"],
+        "sources": _crawl["sources"],
+        "dry_run": _crawl["dry_run"],
+        "stats": _crawl["stats"],
+        "error": _crawl["error"],
+    }
+
+
+# ── Sanitize ──────────────────────────────────────────────────────────────────
+
+@router.post("/sanitize")
+async def admin_sanitize(
+    dry_run: bool = Query(False, description="Report changes without applying them"),
+    _: None = Depends(_check_admin_key),
+    pool=Depends(_get_pool),
+):
+    """Fix non-canonical topic/type labels and remove content-duplicate wiki units."""
+    from app.math_wiki.storage.sanitizer import run_all
+    report = await run_all(pool, dry_run=dry_run)
+    return report

backend/app/math_wiki/agents/classifier.py

@@ -0,0 +1,135 @@
+import json
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+from app.math_wiki.prompts import MODE_PROMPTS
+from app.math_wiki.utils import _extract_json, VALID_LABELS
+from app.math_wiki.taxonomy import CANONICAL_TOPICS  # noqa: F401 — imported for canonical reference
+
+
+async def classify_problem(client: AsyncOpenAI, problem_text: str) -> str:
+    settings = get_settings()
+    user_msg = (
+        f"{problem_text}\n\n"
+        "Respond ONLY with valid JSON in this exact format: "
+        '{"label": "<category>"} '
+        "where category is one of: algebra, geometry, statistics, probability, "
+        "calculus, trigonometry, combinatorics, number_theory, "
+        "complex_numbers, sequences, vectors, functions."
+    )
+    response = await call_with_retry(
+        client,
+        model=settings.default_model,
+        messages=[
+            {"role": "system", "content": MODE_PROMPTS["CLASSIFY"]},
+            {"role": "user", "content": user_msg},
+        ],
+        max_tokens=50,
+    )
+    raw = response.choices[0].message.content or ""
+    content = _extract_json(raw)
+    try:
+        parsed = json.loads(content)
+        label = parsed.get("label", "")
+    except json.JSONDecodeError:
+        label = ""
+
+    keyword_map = {
+            "calculus": [
+                "calculus", "derivative", "integral", "integrate", "differentiat",
+                "limit", r"\int", "antiderivative", "indefinite", "definite",
+                "dy/dx", "d/dx", "partial", "gradient", "divergence", "curl",
+                "differential equation", "ode", "pde", "y''", "y'",
+                # Vietnamese
+                "đạo hàm", "tích phân", "nguyên hàm", "giới hạn", "vi phân",
+                "phương trình vi phân", "cực trị hàm", "tiếp tuyến",
+            ],
+            "trigonometry": [
+                "trigonometry", "trigonometric", "sine", "cosine", "tangent",
+                r"\sin", r"\cos", r"\tan", r"\cot", r"\sec", r"\csc",
+                "sin(", "cos(", "tan(", "arcsin", "arccos", "arctan",
+                # Vietnamese
+                "sin ", "cos ", "tan ", "cot ", "sinx", "cosx", "tanx",
+                "công thức lượng giác", "hệ thức lượng",
+            ],
+            "algebra": [
+                "algebra", "equation", "quadratic", "polynomial", "linear", "variable",
+                # Vietnamese
+                "phương trình", "hệ phương trình", "bất phương trình",
+                "đa thức", "nhân tử", "rút gọn", "hằng đẳng thức",
+            ],
+            "geometry": [
+                "geometry", "geometric", "triangle", "circle", "area", "perimeter", "volume", "angle",
+                # Vietnamese
+                "tam giác", "hình vuông", "hình chữ nhật", "hình thang", "hình tròn",
+                "đường tròn", "hình hộp", "hình chóp", "hình trụ", "hình cầu",
+                "diện tích", "chu vi", "thể tích", "góc", "đường thẳng", "mặt phẳng",
+            ],
+            "statistics": [
+                "statistic", "mean", "median", "mode", "variance", "deviation", "frequency",
+                # Vietnamese
+                "trung bình", "trung vị", "phương sai", "độ lệch chuẩn", "tần số",
+                "bảng số liệu", "biểu đồ",
+            ],
+            "probability": [
+                "probability", "chance", "likelihood", "random", "event",
+                # Vietnamese
+                "xác suất", "biến cố", "ngẫu nhiên", "không gian mẫu",
+            ],
+            "combinatorics": [
+                "combinatoric", "permutation", "combination", "factorial", "arrange",
+                # Vietnamese
+                "tổ hợp", "chỉnh hợp", "hoán vị", "giai thừa", "đếm",
+            ],
+            "number_theory": [
+                "number theory", "prime", "divisor", "modular", "gcd", "lcm",
+                # Vietnamese
+                "số nguyên tố", "ước", "bội", "chia hết", "đồng dư", "ucln", "bcnn",
+            ],
+            "sequences": [
+                # Vietnamese
+                "dãy số", "cấp số cộng", "cấp số nhân", "công sai", "công bội",
+                "số hạng", "tổng n số hạng", "giới hạn dãy",
+                # English
+                "sequence", "series", "arithmetic sequence", "geometric sequence",
+            ],
+            "vectors": [
+                # Vietnamese
+                "vectơ", "tích vô hướng", "tích có hướng", "tọa độ vectơ",
+                # English
+                "vector", "dot product", "cross product", "magnitude",
+            ],
+            "functions": [
+                # Vietnamese
+                "hàm số", "đồ thị hàm số", "tập xác định", "tập giá trị",
+                "đơn điệu", "đồng biến", "nghịch biến", "hàm bậc", "hàm mũ", "h��m logarit",
+                # English
+                "function", "domain", "range", "monoton",
+            ],
+            "complex_numbers": [
+                # Vietnamese
+                "số phức", "phần thực", "phần ảo", "module", "argument",
+                # English
+                "complex number", "imaginary", "real part", "imaginary part",
+            ],
+        }
+
+    # Score every label by counting keyword hits. Highest score wins.
+    # First-match (next(...)) was order-dependent: "phương trình vi phân" matched
+    # algebra ("phương trình") before calculus, mis-classifying ODEs.
+    question_lower = problem_text.lower()
+    scores: dict[str, int] = {}
+    for lbl, kws in keyword_map.items():
+        count = sum(1 for kw in kws if kw in question_lower)
+        if count:
+            scores[lbl] = count
+    keyword_label = max(scores, key=scores.__getitem__) if scores else None
+
+    if label not in VALID_LABELS:
+        label = keyword_label or "algebra"
+    elif keyword_label and keyword_label != label:
+        # Keyword score beats LLM label only when it has strictly more hits.
+        # Tie means ambiguous — keep the LLM's more contextual judgement.
+        if scores.get(keyword_label, 0) > scores.get(label, 0):
+            label = keyword_label
+    return label

backend/app/math_wiki/agents/concept_ingest.py

@@ -0,0 +1,83 @@
+import hashlib
+import json
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+from app.math_wiki.prompts import MODE_PROMPTS
+from app.math_wiki.utils import _extract_json
+from app.math_wiki.schemas import ConceptIngestOutput
+from app.math_wiki.storage import pg_db
+from app.math_wiki.storage.pg_vectors import is_near_duplicate_pg
+from app.metrics import inc_wiki_units_added
+from app.math_wiki.taxonomy import CANONICAL_TOPICS, TOPIC_MAP, CANONICAL_TYPES, TYPE_MAP
+
+_VALID_TOPICS = ", ".join(sorted(CANONICAL_TOPICS))
+_VALID_TYPES = ", ".join(sorted(CANONICAL_TYPES))
+
+_JSON_REMINDER = (
+    "\n\nExtract wiki knowledge units from the above math text. "
+    "Return ONLY valid JSON in this exact format: "
+    '{"wiki_units": [{"id": "slug", "type": "concept", "topic": "statistics", '
+    '"subtopic": "...", "content": "...", "problem_ids": []}]}\n'
+    f"topic MUST be one of: {_VALID_TOPICS}\n"
+    f"type MUST be one of: {_VALID_TYPES}\n"
+    "IMPORTANT: Write math expressions in plain text (e.g. 'x^2 + bx + c = 0'), "
+    "NOT LaTeX backslash notation. Backslashes break JSON."
+)
+
+
+def _normalize_unit(unit, fallback_topic: str | None) -> None:
+    topic = unit.topic
+    if topic not in CANONICAL_TOPICS:
+        topic = TOPIC_MAP.get(topic) or TOPIC_MAP.get(topic.lower().replace(" ", "_"))
+    if topic not in CANONICAL_TOPICS:
+        topic = fallback_topic
+    if topic:
+        unit.topic = topic
+
+    unit_type = unit.type
+    if unit_type not in CANONICAL_TYPES:
+        unit.type = TYPE_MAP.get(unit_type, "concept")
+
+
+async def concept_ingest(
+    client: AsyncOpenAI,
+    raw_text: str,
+    pool=None,
+    source: str = "manual",
+    source_url: str | None = None,
+    fallback_topic: str | None = None,
+) -> ConceptIngestOutput:
+    settings = get_settings()
+    response = await call_with_retry(
+        client,
+        model=settings.default_model,
+        messages=[
+            {"role": "system", "content": MODE_PROMPTS["CONCEPT_INGEST"]},
+            {"role": "user", "content": raw_text + _JSON_REMINDER},
+        ],
+        max_tokens=4096,
+    )
+    content = _extract_json(response.choices[0].message.content or "{}")
+    parsed = json.loads(content)
+    output = ConceptIngestOutput(**parsed)
+
+    if pool:
+        existing_hashes = await pg_db.get_all_content_hashes(pool)
+        for unit in output.wiki_units:
+            _normalize_unit(unit, fallback_topic)
+            if unit.topic not in CANONICAL_TOPICS:
+                logger.warning("concept_ingest: skipped %s — invalid topic %r (not in CANONICAL_TOPICS)", unit.id, unit.topic)
+                continue
+            content_hash = hashlib.md5(unit.content.encode()).hexdigest()
+            if content_hash in existing_hashes:
+                logger.info("concept_ingest: skipped %s — duplicate content hash", unit.id)
+                continue
+            if await is_near_duplicate_pg(pool, unit.content):
+                logger.info("concept_ingest: skipped %s — near-duplicate by embedding (similarity>0.92)", unit.id)
+                continue
+            await pg_db.upsert_wiki_unit(pool, unit, source=source, source_url=source_url)
+            existing_hashes.add(content_hash)
+            inc_wiki_units_added()
+
+    return output

backend/app/math_wiki/agents/decomposer.py

@@ -0,0 +1,63 @@
+"""Multi-domain query decomposer.
+
+Detects when a problem spans two THPT math topics and splits it into
+focused sub-questions for independent retrieval.
+Returns quickly (Haiku) and is non-fatal — callers catch all exceptions.
+"""
+import json
+import logging
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+from app.math_wiki.utils import _extract_json
+from app.math_wiki.schemas import DecomposedQuery
+
+logger = logging.getLogger(__name__)
+
+_PROMPT = """Bạn là hệ thống phân tích lĩnh vực toán học cho kỳ thi THPT Việt Nam.
+
+Cho một bài toán, xác định xem bài toán có THỰC SỰ cần kiến thức từ hai chủ đề THPT riêng biệt không.
+Trả lời bằng tiếng Việt. Chỉ xuất JSON theo đúng schema sau:
+
+{
+  "primary_topic": "algebra",
+  "secondary_topics": ["calculus"],
+  "sub_questions": ["Tìm f'(x)", "Giải f'(x)=0"],
+  "requires_multi_domain": true
+}
+
+Chủ đề THPT: algebra, calculus, geometry, trigonometry, combinatorics, probability, statistics, logarithm, functions, spatial_geometry
+
+Quy tắc:
+- requires_multi_domain = true CHỈ KHI bài toán KHÔNG THỂ giải được chỉ với kiến thức từ một chủ đề duy nhất.
+- sub_questions: 2-3 câu hỏi phụ bằng tiếng Việt, phân tách bài toán theo từng chủ đề.
+- Nếu bài toán chỉ thuộc một chủ đề, đặt requires_multi_domain=false và sub_questions=[].
+- Chỉ xuất JSON hợp lệ. Không viết thêm bất kỳ văn bản nào."""
+
+
+async def decompose_query(client: AsyncOpenAI, question: str) -> DecomposedQuery:
+    settings = get_settings()
+    response = await call_with_retry(
+        client,
+        model=settings.haiku_model,
+        messages=[
+            {"role": "system", "content": _PROMPT},
+            {"role": "user", "content": question},
+        ],
+        max_tokens=256,
+    )
+    content = _extract_json(response.choices[0].message.content or "{}")
+    try:
+        parsed = json.loads(content)
+    except json.JSONDecodeError:
+        return DecomposedQuery(
+            primary_topic="algebra", secondary_topics=[],
+            sub_questions=[], requires_multi_domain=False,
+        )
+
+    return DecomposedQuery(
+        primary_topic=parsed.get("primary_topic", "algebra"),
+        secondary_topics=parsed.get("secondary_topics", []),
+        sub_questions=parsed.get("sub_questions", []),
+        requires_multi_domain=bool(parsed.get("requires_multi_domain", False)),
+    )

backend/app/math_wiki/agents/ingest.py

@@ -0,0 +1,64 @@
+import hashlib
+import json
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+from app.math_wiki.prompts import MODE_PROMPTS
+from app.math_wiki.utils import _extract_json
+from app.math_wiki.schemas import IngestOutput
+from app.math_wiki.storage import pg_db
+from app.math_wiki.storage.pg_vectors import is_near_duplicate_pg
+from app.metrics import inc_wiki_units_added
+
+
+async def ingest_exam(
+    client: AsyncOpenAI,
+    raw_text: str,
+    pool=None,
+    source: str = "exam_upload",
+    source_url: str | None = None,
+) -> IngestOutput:
+    settings = get_settings()
+    response = await call_with_retry(
+        client,
+        model=settings.default_model,
+        messages=[
+            {"role": "system", "content": MODE_PROMPTS["INGEST"]},
+            {"role": "user", "content": raw_text},
+        ],
+        max_tokens=2000,
+    )
+    content = _extract_json(response.choices[0].message.content or "{}")
+    parsed = json.loads(content)
+    output = IngestOutput(**parsed)
+
+    # Validate: each problem must have >= 2 wiki units
+    unit_map: dict[str, set[str]] = {}
+    for unit in output.wiki_units:
+        for pid in unit.problem_ids:
+            unit_map.setdefault(pid, set()).add(unit.id)
+
+    for problem in output.problems:
+        if len(unit_map.get(problem.problem_id, set())) < 2:
+            raise ValueError(
+                f"Problem {problem.problem_id} has fewer than 2 wiki units"
+            )
+
+    if pool:
+        existing_hashes = await pg_db.get_all_content_hashes(pool)
+        for unit in output.wiki_units:
+            content_hash = hashlib.md5(unit.content.encode()).hexdigest()
+            if content_hash in existing_hashes:
+                logger.info("ingest: skipped %s — duplicate content hash", unit.id)
+                continue
+            if await is_near_duplicate_pg(pool, unit.content):
+                logger.info("ingest: skipped %s — near-duplicate by embedding (similarity>0.92)", unit.id)
+                continue
+            await pg_db.upsert_wiki_unit(pool, unit, source=source, source_url=source_url)
+            existing_hashes.add(content_hash)
+            inc_wiki_units_added()
+
+        for problem in output.problems:
+            await pg_db.upsert_problem(pool, problem)
+
+    return output

backend/app/math_wiki/agents/ocr.py

@@ -0,0 +1,73 @@
+import base64
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+
+# Phrases Claude returns when image content was stripped by the proxy
+_NO_IMAGE_PHRASES = (
+    "chưa đính kèm hình ảnh",
+    "không thấy hình ảnh",
+    "không có hình ảnh",
+    "vui lòng tải lên hình ảnh",
+    "vui lòng gửi hình ảnh",
+    "no image attached",
+    "no image provided",
+    "i don't see any image",
+)
+
+_SYSTEM_PROMPT = (
+    "You are a Vietnamese math OCR assistant. Extract all text, mathematical content, and visual elements from the image.\n"
+    "Rules:\n"
+    "- Preserve all LaTeX notation exactly; wrap inline math in $...$  and display math in $$...$$\n"
+    "- Keep Vietnamese text exactly as written\n"
+    "- List each numbered problem separately\n"
+    "- Do not solve or explain — only transcribe or describe what is visible\n"
+    "- If a symbol is unclear, use your best judgment\n"
+    "- For handwritten content: interpret symbols especially carefully. Common handwritten forms:\n"
+    "  fraction a/b → \\frac{a}{b}; square root → \\sqrt{}; exponent → ^{}; subscript → _{};\n"
+    "  absolute value bars → |...|; multiplication dot → \\cdot\n"
+    "- When a symbol is ambiguous, choose the most mathematically plausible interpretation\n"
+    "- Preserve problem number labels exactly as they appear (Bài 1, Câu 2, etc.)\n"
+    "Visual elements — when the image contains shapes, graphs, or drawings that cannot be expressed as plain text:\n"
+    "- Geometric figures: describe the shape (triangle, circle, quadrilateral…), label each vertex/point as shown,"
+    " list all given side lengths, angles, and any marked equal/parallel/perpendicular relationships."
+    " Example: 'Tam giác ABC vuông tại A, AB = 3, BC = 5, AC = 4'\n"
+    "- Coordinate graphs / function plots: state axis labels and scale, identify key points (intercepts, maxima,"
+    " minima, intersection points) with their coordinates, describe the curve type (line, parabola, circle…)."
+    " Example: 'Đồ thị hàm số y = f(x) qua các điểm (0, 2) và (3, 0), là đường thẳng giảm dần'\n"
+    "- Hand-drawn or complex diagrams: give a concise prose description of every element, dimension, and label"
+    " that appears, sufficient for a solver to reconstruct the problem without seeing the image\n"
+    "- Place visual descriptions inline, immediately after the problem text they accompany"
+)
+
+
+async def extract_math_from_image(
+    client: AsyncOpenAI, image_bytes: bytes, mime_type: str
+) -> str:
+    settings = get_settings()
+    data_uri = f"data:{mime_type};base64,{base64.b64encode(image_bytes).decode()}"
+
+    response = await call_with_retry(
+        client,
+        model=settings.default_model,
+        messages=[
+            {"role": "system", "content": _SYSTEM_PROMPT},
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image_url", "image_url": {"url": data_uri}},
+                    {"type": "text", "text": "Trích xuất toàn bộ nội dung toán học từ hình ảnh này."},
+                ],
+            },
+        ],
+        max_tokens=4096,
+    )
+
+    text = (response.choices[0].message.content or "").strip()
+    if not text:
+        raise ValueError("Claude Vision returned empty response")
+    if any(phrase in text.lower() for phrase in _NO_IMAGE_PHRASES):
+        raise ValueError(
+            "Vision API not supported by this AI router — please type the problem manually."
+        )
+    return text

backend/app/math_wiki/agents/quiz_generator.py

@@ -0,0 +1,471 @@
+import json
+import logging
+import random
+import re
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+
+logger = logging.getLogger(__name__)
+
+# Sources for distractor taxonomy and techniques:
+# - Vanderbilt / Lamar algebra error catalogs (sign, distribution, sqrt errors)
+# - NAACL 2024: naming error mechanisms raises distractor plausibility ~2.68→~3.7 on 5-pt scale
+# - INFORMS 2022: partial-solution and conceptual-reversal are most convincing traps in quant MCQs
+# - Student Choice Prediction (ACL 2025): conceptual-overlap traps attract highest-ability students
+# - LookAlike ACL 2025: surface-form consistency across all options blocks answer-by-elimination
+# - NYSED item writing guide: sign/coefficient/unit alteration as a systematic distractor family
+_SYSTEM = r"""Bạn là giáo viên Toán lớp 9 chuyên ôn thi vào lớp 10 TPHCM, đồng thời là chuyên gia thiết kế đề trắc nghiệm.
+Nhiệm vụ: tạo câu hỏi trắc nghiệm chất lượng cao — mỗi phương án sai phải dựa trên lỗi nhận thức thực sự của học sinh và không thể loại bằng hình thức.
+
+═══ NGUYÊN TẮC CỐT LÕI ═══
+
+1. TÍNH NHẨM ĐƯỢC: Mọi con số phải tính được bằng đầu óc — KHÔNG cần máy tính.
+2. 4 PHƯƠNG ÁN: Mỗi câu có đúng 4 lựa chọn (A–D), chỉ một đúng.
+3. BẪY CÓ NGUỒN GỐC: Mỗi phương án sai PHẢI xuất phát từ một loại lỗi cụ thể trong bảng taxonomy.
+   Ba bẫy trong một câu phải đến từ BA loại lỗi KHÁC NHAU.
+4. LOOKALIKE — NGOẠI HÌNH GIỐNG NHAU: Tất cả 4 phương án phải có cùng dạng ký hiệu, cùng cấu trúc
+   (cùng loại biểu thức, số hạng tương đương, độ phức tạp tương tự). Học sinh không được loại
+   phương án sai chỉ bằng cách nhìn hình thức mà phải tính toán.
+5. TỰ KIỂM TRA: Tính lại đáp án đúng từng bước trước khi viết JSON. Xác nhận mỗi bẫy thực sự sai.
+6. ĐỘ KHÓ BLOOM: Sắp xếp từ dễ → khó theo thang nhận thức.
+7. NGÔN NGỮ: Tiếng Việt. LaTeX trong $...$ cho ký hiệu toán.
+8. JSON THUẦN: Chỉ trả về JSON, không có text ngoài.
+
+═══ BẢNG LỖI SAI THỰC CHỨNG (DISTRACTOR TAXONOMY) ═══
+
+Mỗi bẫy phải thuộc một trong 13 loại sau — ghi tên loại trong explanation:
+
+── NHÓM DẤU VÀ HỆ SỐ ──
+
+[SIGN_ERROR] Nhầm dấu âm/dương
+  • $-(a-b)$ → ghi $-a-b$ thay vì $-a+b$
+  • Tổng Viète $x_1+x_2=-b/a$ → ghi $+b/a$ (bỏ dấu âm)
+  • Tích Viète $x_1x_2=c/a$ → ghi $-c/a$
+  • $-x$ khi $x=-5$ → ghi $-5$ thay vì $5$
+
+[COEFFICIENT_ERROR] Sai hệ số hoặc bội số
+  • $(a+b)^2=a^2+2ab+b^2$ → bỏ hệ số 2: viết $a^2+ab+b^2$
+  • $\Delta=b^2-4ac$ → viết $b^2-ac$ (quên hệ số 4)
+  • $2a\cdot x_0 = -b$ → viết $a\cdot x_0=-b$ (quên hệ số 2)
+  • Kết quả đúng nhân hay chia thêm 2, 4, hoặc $\pi$ do nhầm công thức
+
+[WRONG_OPERATION] Dùng phép tính sai — số đúng, phép tính sai
+  • Cộng thay nhân: $P = a \times b$ → viết $P = a + b$
+  • Bình phương thay nhân đôi: $2r$ → viết $r^2$
+  • Khai căn thay bình phương: $x^2=k$ → ghi $x=k^2$ thay $x=\sqrt{k}$
+  • Chia thay trừ trong hệ thức lượng
+
+── NHÓM NGHIỆM VÀ MIỀN ──
+
+[MISSING_ROOT] Bỏ sót nghiệm
+  • $x^2=9$ → chỉ lấy $x=3$, quên $x=-3$
+  • Chia hai vế cho $x$ → mất nghiệm $x=0$
+  • $|x|=5$ → quên $x=-5$
+  • Phương trình tích: chỉ lấy một trong hai nghiệm
+
+[EXTRANEOUS_ROOT] Nghiệm ngoại lai (không kiểm tra lại)
+  • Bình phương hai vế rồi không thử lại vào phương trình gốc
+  • Đặt ẩn phụ $t=\sqrt{x}\geq0$ rồi nhận $t<0$
+  • Nhận nghiệm nằm ngoài điều kiện xác định
+
+[INEQUALITY_FLIP] Quên đảo chiều bất phương trình
+  • Nhân/chia hai vế với số âm mà không lật dấu $\leq\to\geq$
+  • Kết quả là phần bù của tập nghiệm đúng
+
+── NHÓM CĂN VÀ PHÂN PHỐI ──
+
+[SQRT_LINEARITY] Giả sử căn là tuyến tính
+  • $\sqrt{a^2+b^2}\to a+b$ (cộng thẳng, bỏ dấu căn)
+  • $\sqrt{(a+b)^2}=a+b$ (bỏ trị tuyệt đối)
+  • $\sqrt{9+16}=3+4=7$ thay vì $\sqrt{25}=5$
+
+[SQRT_NO_ABS] Quên trị tuyệt đối khi khai căn
+  • $\sqrt{x^2}=x$ thay vì $|x|$
+  • $\sqrt{(x-3)^2}=x-3$ thay vì $|x-3|$
+
+[DISTRIBUTION_ERROR] Phân phối/nhân sai
+  • $(a+b)^2\neq a^2+b^2$ (bỏ hạng tử $2ab$)
+  • $a(b-c)^2\neq(ab-ac)^2$: nhân $a$ vào trước khi bình phương
+  • $\frac{a+b}{c}\neq\frac{a}{c}+b$: chỉ rút gọn một hạng tử
+
+── NHÓM CÔNG THỨC VÀ KHÁI NIỆM ──
+
+[DELTA_ERROR] Sai công thức Delta
+  • $\Delta=b^2-4ac$: nhầm dấu $c$, hoặc dùng $b$ thay $b'=b/2$
+  • Chỉ lấy một nghiệm $x_1$ hoặc chỉ lấy $x_2$
+
+[CONCEPTUAL_REVERSAL] Đảo ngược một quan hệ toán học
+  • Phân số: $\frac{a}{b}\to\frac{b}{a}$ (đảo tử/mẫu)
+  • Tỉ số lượng giác: $\sin\theta=\frac{\text{đối}}{\text{huyền}}$ → dùng $\frac{\text{huyền}}{\text{đối}}$
+  • Viète: dùng tổng thay tích hoặc ngược lại
+  • Hệ thức: $x_1\cdot x_2=c/a$ → học sinh dùng $x_1+x_2$
+  • Tỉ lệ thức: $\frac{a}{b}=\frac{c}{d}$ → giải nhầm thành $ad=bc$ rồi hoán vị sai
+
+[VERTEX_SIGN] Nhầm dấu tọa độ đỉnh parabol
+  • $x_0=-b/(2a)$ → dùng $+b/(2a)$
+  • Tính $f(x_0)$ nhưng thay $-x_0$
+
+[FORMULA_MIX] Nhầm công thức hoặc điều kiện áp dụng
+  • Diện tích/chu vi: nhầm hình tròn với hình quạt hay hình chữ nhật
+  • Định lý Pythagore: nhầm vai trò cạnh huyền
+  • Hệ thức lượng trong tam giác vuông: nhầm cạnh với chiều cao
+
+── NHÓM ĐẶC BIỆT: BẪY MẠNH NHẤT ──
+
+[PARTIAL_SOLUTION] Nghiệm trung gian — học sinh dừng lại quá sớm
+  Đây là loại bẫy hiệu quả nhất với học sinh giỏi.
+  Kỹ thuật: lấy KẾT QUẢ CỦA BƯỚC TRUNG GIAN đúng trong lời giải đầy đủ làm phương án sai.
+  • Bài 3 bước: kết quả bước 2 là đáp án trông "hợp lý" nhất
+  • Tìm $x$: học sinh tính được $2x=10$ rồi ghi ngay $10$ thay vì $5$
+  • Tìm diện tích: tính đúng bán kính $r$ rồi ghi $r$ thay vì $\pi r^2$
+  • Giải hệ: tìm đúng $x$ rồi quên thay vào tìm $y$
+  Cách tạo: Viết lời giải đầy đủ 4–5 bước → lấy kết quả bước 2 và bước 3 làm hai bẫy.
+
+═══ QUY TRÌNH ESSAY-TO-MCQ (chuyển bài tự luận thành trắc nghiệm) ═══
+
+Đây là kỹ thuật cốt lõi để tạo bẫy cực kỳ thuyết phục:
+
+Bước 1 — Viết lời giải tự luận đầy đủ:
+  Liệt kê từng bước tính: $k_1=\ldots$, $k_2=\ldots$, $k_3=\ldots$, đáp án $=k_n$.
+
+Bước 2 — Thu hoạch bẫy từ lời giải:
+  • Bẫy A = $k_{n-1}$ (kết quả bước cuối-1): [PARTIAL_SOLUTION]
+  • Bẫy B = kết quả nếu dùng sai công thức tại bước quan trọng nhất: [FORMULA_MIX] hoặc [DELTA_ERROR]
+  • Bẫy C = đáp án đúng nhưng đổi dấu hoặc đảo tử/mẫu: [SIGN_ERROR] hoặc [CONCEPTUAL_REVERSAL]
+
+Bước 3 — Áp dụng nguyên tắc LOOKALIKE:
+  Đảm bảo A, B, C, D (đáp án đúng) cùng dạng: đều là số nguyên, đều là phân số, đều có $\sqrt{}$,
+  cùng số hạng, giá trị gần nhau về độ lớn.
+
+Bước 4 — Sắp xếp các phương án theo thứ tự tăng dần (với số) hoặc theo độ phức tạp.
+
+Bước 5 — Kiểm tra: Đọc từng bẫy và tự hỏi "Học sinh nào sẽ chọn cái này và tại sao?"
+  Bẫy tốt = có câu trả lời rõ ràng cho câu hỏi đó.
+
+═══ THANG ĐỘ KHÓ BLOOM ═══
+
+"easy"   → Nhớ/Hiểu: nhận dạng công thức, tính một bước, bẫy là lỗi cơ bản (SIGN_ERROR, MISSING_ROOT)
+"medium" → Vận dụng: giải 2–3 bước, bẫy bao gồm PARTIAL_SOLUTION từ bước trung gian
+"hard"   → Phân tích/Đánh giá: 3–5 bước, hai bẫy kết hợp (ví dụ PARTIAL_SOLUTION + CONCEPTUAL_REVERSAL),
+           điều kiện ẩn, học sinh giỏi vẫn có thể mắc bẫy nếu không kiểm tra kỹ
+
+═══ TỰ KIỂM TRA BẮT BUỘC TRƯỚC KHI XUẤT JSON ═══
+
+Sau khi tạo xong từng câu, thực hiện kiểm tra sau — nếu không qua thì viết lại câu đó:
+
+CHK-1  TOÁN HỌC CHÍNH XÁC — GIẢI TRƯỚC KHI ĐẶT correct_index
+  → Viết lời giải tự luận đầy đủ từng bước số học cụ thể.
+  → Ghi kết quả cuối: "Đáp án đúng = <giá trị>".
+  → Tìm phần tử trong choices khớp giá trị đó → đó là correct_index.
+  → Xác nhận 3 phương án còn lại đều SAI.
+  → KHÔNG được gán correct_index trước rồi mới giải — luôn giải trước, gán sau.
+
+CHK-2  NHẤT QUÁN GIẢI THÍCH — ĐÁP ÁN
+  → Nội dung "Đáp án đúng:" trong explanation PHẢI KHỚP giá trị số với choices[correct_index].
+  → Nếu không khớp → viết lại câu từ đầu.
+
+CHK-3  NHẤT QUÁN BẪY — EXPLANATION
+  → Với mỗi bẫy (phương án sai), explanation phải ghi đúng tên loại lỗi và cơ chế sai khớp với giá trị trong choices.
+
+CHK-4  LOOKALIKE ĐỦ ĐIỀU KIỆN
+  → Tất cả 4 phương án cùng dạng ký hiệu và cấu trúc.
+  → Không có phương án nào quá dài/ngắn hoặc phức tạp khác biệt rõ ràng so với các phương án khác.
+
+CHK-5  EXPLANATION NGẮN GỌN — KHÔNG BIỆN HỘ SAU
+  → Explanation CHỈ được giải bài toán GỐC trong stem — KHÔNG được thử nghiệm thay đổi đề bài.
+  → Nếu tính toán cho kết quả không khớp choices nào → viết lại câu hỏi để sửa, KHÔNG viết dài thêm để biện hộ.
+  → Giới hạn: phần "Đáp án đúng:" tối đa 4 câu/bước; mỗi bẫy tối đa 1 câu ngắn.
+
+QUAN TRỌNG: correct_index trong JSON PHẢI trỏ đúng vào phương án chứa đáp án đã tính ở CHK-1.
+Đây là điều kiện tối thiểu — sai ở đây là lỗi nghiêm trọng nhất."""
+
+_PROMPT_TMPL = """Trọng tâm tuần: {focus}
+Nhiệm vụ học trong tuần:
+{tasks}
+
+Ngữ cảnh kiến thức từ kho tri thức:
+{context}
+
+Tạo {n} câu hỏi trắc nghiệm (từ dễ → khó theo Bloom).
+
+YÊU CẦU BẮT BUỘC cho mỗi câu:
+1. Áp dụng quy trình Essay-to-MCQ: viết lời giải tự luận trước, sau đó thu hoạch bẫy.
+2. Đảm bảo nguyên tắc LOOKALIKE: 4 phương án cùng dạng ký hiệu, giá trị gần nhau.
+3. Ba bẫy từ ba loại lỗi KHÁC NHAU trong taxonomy.
+4. Explanation nêu rõ: tính toán đáp án đúng + tên loại lỗi + cơ chế sai của từng bẫy.
+5. PHÂN BỐ correct_index: trong {n} câu, đáp án đúng phải rải đều A/B/C/D — KHÔNG được tập trung vào một vị trí. Đặt đáp án đúng vào vị trí bất kỳ (0, 1, 2, hoặc 3) sau khi sắp xếp choices.
+
+Trả về JSON hợp lệ, không có text nào ngoài JSON:
+{{
+  "questions": [
+    {{
+      "stem": "Nội dung câu hỏi (tiếng Việt, LaTeX $...$)",
+      "choices": ["A. ...", "B. ...", "C. ...", "D. ..."],
+      "correct_index": "<số nguyên 0-3, phân bố đều giữa các câu — KHÔNG luôn là 0>",
+      "difficulty": "easy|medium|hard",
+      "bloom_level": "remember|understand|apply|analyze",
+      "explanation": "Đáp án đúng: <lời giải từng bước>. Bẫy <tên PA sai 1> [LOẠI_LỖI]: <cơ chế>. Bẫy <tên PA sai 2> [LOẠI_LỖI]: <cơ chế>. Bẫy <tên PA sai 3> [LOẠI_LỖI]: <cơ chế>."
+    }}
+  ]
+}}"""
+
+
+# Reviewer prompt: independent mathematical validation of each generated question.
+# Uses default_model (sonnet) because haiku cannot reliably verify multi-step algebra
+# (Vieta, completing the square, optimization with constraints, etc.).
+_REVIEWER_SYSTEM = r"""Bạn là giáo viên Toán lớp 9 kiểm duyệt độc lập. Với MỖI câu hỏi:
+
+BƯỚC 1 — GIẢI ĐỘC LẬP (bắt buộc, không đọc explanation trước):
+  Đọc "stem". Tính kết quả đúng từ đầu theo từng bước số học cụ thể.
+  Ghi kết quả tính được: result = <giá trị cụ thể>.
+
+BƯỚC 2 — ĐỐI CHIẾU VỚI CHOICES:
+  Tìm phần tử trong "choices" chứa giá trị = result ở Bước 1.
+  Đó là correct_index thực sự (0=A, 1=B, 2=C, 3=D).
+
+BƯỚC 3 — SO SÁNH VỚI correct_index ĐÃ CHO:
+  Nếu correct_index đã cho = correct_index thực sự → valid: true.
+  Nếu khác → valid: false, báo corrected_correct_index = correct_index thực sự.
+  Nếu không có choice nào khớp result → valid: false, corrected_correct_index: null (bỏ câu).
+
+QUY TẮC QUAN TRỌNG:
+- KHÔNG được tin vào explanation — nó có thể sai hoặc cố tình biện hộ cho đáp án sai.
+- KHÔNG được chấp nhận lý luận dài dòng thay đổi đề bài. Chỉ kiểm tra stem gốc.
+- Nếu explanation mâu thuẫn với kết quả tính ở Bước 1 → luôn tin vào tính toán, không tin explanation.
+
+Trả về JSON thuần (không có text ngoài):
+{"results": [{"index": <i>, "valid": true|false, "corrected_correct_index": <j|null>}]}"""
+
+
+async def _review_and_patch(
+    client: AsyncOpenAI,
+    questions: list[dict],
+    settings,
+) -> list[dict]:
+    """Send generated questions to a reviewer model; drop or patch invalid ones."""
+    if not questions:
+        return questions
+
+    payload = json.dumps({"questions": questions}, ensure_ascii=False)
+    try:
+        response = await call_with_retry(
+            client,
+            model=settings.default_model,
+            max_tokens=3000,
+            messages=[
+                {"role": "system", "content": _REVIEWER_SYSTEM},
+                {"role": "user", "content": payload},
+            ],
+        )
+        raw = _extract_json(response.choices[0].message.content or "{}")
+        data = json.loads(raw)
+        results = {r["index"]: r for r in data.get("results", [])}
+    except Exception as exc:
+        logger.warning("quiz_generator: reviewer call failed (%s), skipping review", exc)
+        return questions
+
+    patched: list[dict] = []
+    for i, q in enumerate(questions):
+        verdict = results.get(i)
+        if verdict is None or verdict.get("valid"):
+            patched.append(q)
+            continue
+        corrected = verdict.get("corrected_correct_index")
+        if corrected is not None and 0 <= corrected < len(q.get("choices", [])):
+            logger.info(
+                "quiz_generator: patching correct_index %d→%d for question %d (issues: %s)",
+                q["correct_index"], corrected, i, verdict.get("issues"),
+            )
+            q = dict(q, correct_index=corrected)
+            patched.append(q)
+        else:
+            logger.warning(
+                "quiz_generator: dropping question %d — reviewer flagged unfixable issues: %s",
+                i, verdict.get("issues"),
+            )
+    return patched
+
+
+def _fix_latex_escapes(text: str) -> str:
+    """Double-escape backslashes that are not valid JSON escape sequences.
+
+    LLMs frequently emit bare LaTeX (e.g. \\sqrt, \\frac) inside JSON strings.
+    Valid JSON escapes after '\\' are: " \\ / b f n r t u.
+    """
+    return re.sub(r'\\(?!["\\/bfnrtu])', r'\\\\', text)
+
+
+def _extract_json(text: str) -> str:
+    """Strip code fences, repair LaTeX escapes, and extract a valid JSON object."""
+    text = text.strip()
+    if text.startswith("```"):
+        parts = text.split("```")
+        text = parts[1] if len(parts) > 1 else text
+        if text.startswith("json"):
+            text = text[4:]
+        text = text.strip()
+    try:
+        json.loads(text)
+        return text
+    except json.JSONDecodeError:
+        pass
+    fixed = _fix_latex_escapes(text)
+    try:
+        json.loads(fixed)
+        return fixed
+    except json.JSONDecodeError:
+        pass
+    m = re.search(r'\{[\s\S]*\}', text)
+    if m:
+        candidate = m.group(0)
+        return _fix_latex_escapes(candidate)
+    return fixed
+
+
+def _validate_structure(questions: list[dict]) -> list[dict]:
+    """Deterministic post-generation guard before questions reach the UI.
+
+    Hard drops (structural):
+      - correct_index not an int 0-3
+      - choices count != 4
+      - any choice is empty/missing
+      - stem is empty
+
+    Soft warns (content consistency — LLM reviewer already validated the math):
+      - explanation missing "Đáp án đúng" section
+      - choices[correct_index] value not found in explanation answer section
+    """
+    valid: list[dict] = []
+    for i, q in enumerate(questions):
+        ci = q.get("correct_index")
+        choices = q.get("choices") or []
+        stem = (q.get("stem") or "").strip()
+        explanation = (q.get("explanation") or "").strip()
+
+        # ── Hard structural checks ──────────────────────────────────────────
+        if not isinstance(ci, int) or not (0 <= ci <= 3):
+            logger.warning("quiz_validate: q%d dropped — invalid correct_index %r", i, ci)
+            continue
+        if len(choices) != 4:
+            logger.warning("quiz_validate: q%d dropped — expected 4 choices, got %d", i, len(choices))
+            continue
+        if not all(isinstance(c, str) and c.strip() for c in choices):
+            logger.warning("quiz_validate: q%d dropped — empty or non-string choice", i)
+            continue
+        if not stem:
+            logger.warning("quiz_validate: q%d dropped — empty stem", i)
+            continue
+
+        # ── Soft content-consistency checks (warn only) ─────────────────────
+        if not explanation:
+            logger.warning("quiz_validate: q%d has no explanation", i)
+        elif "Đáp án đúng" not in explanation:
+            logger.warning("quiz_validate: q%d explanation missing 'Đáp án đúng' section", i)
+        else:
+            # Extract correct choice value (strip "A. " label and LaTeX $ markers + whitespace)
+            correct_body = re.sub(r'^[A-D]\.\s*', '', choices[ci]).strip()
+            # Get answer section (text before first "Bẫy" label)
+            ans_section = re.split(r'\bBẫy\s+[A-D]\b', explanation, maxsplit=1)[0]
+
+            def _norm(s: str) -> str:
+                return re.sub(r'[\s$]', '', s)
+
+            if correct_body and _norm(correct_body) not in _norm(ans_section):
+                logger.warning(
+                    "quiz_validate: q%d explanation/answer mismatch — "
+                    "choice[%d]=%r not found in answer section %r",
+                    i, ci, correct_body[:50], ans_section[:100],
+                )
+
+        valid.append(q)
+    return valid
+
+
+def _shuffle_answer_position(questions: list[dict]) -> list[dict]:
+    """Randomly redistribute the correct answer across A/B/C/D positions.
+
+    LLMs have a strong bias toward correct_index=0. This post-processor
+    reassigns each question's correct answer to a random position so the
+    distribution is uniform regardless of what the model output.
+    """
+    result = []
+    for q in questions:
+        old_idx = q["correct_index"]
+        choices = list(q["choices"])
+        new_idx = random.randint(0, 3)
+        if new_idx != old_idx:
+            choices[old_idx], choices[new_idx] = choices[new_idx], choices[old_idx]
+            # Re-label A/B/C/D to match new positions
+            relabeled = []
+            for i, c in enumerate(choices):
+                label = chr(65 + i) + ". "
+                body = re.sub(r'^[A-D]\.\s*', '', c)
+                relabeled.append(label + body)
+            q = dict(q, choices=relabeled, correct_index=new_idx)
+        result.append(q)
+    return result
+
+
+async def generate_week_quiz(
+    client: AsyncOpenAI,
+    pool,
+    week_focus: str,
+    week_tasks: list[str],
+    n: int = 4,
+) -> list[dict]:
+    """Generate n MCQ for a study-plan week, grounded in wiki knowledge."""
+    context = ""
+    if pool:
+        try:
+            from app.math_wiki.storage import pg_vectors, pg_db
+            query = week_focus + " " + " ".join(week_tasks)
+            ids = await pg_vectors.query_pgvector(pool, query, top_k=8)
+            units = await pg_db.get_wiki_units_by_ids(pool, ids) if ids else []
+            if units:
+                context = "\n\n".join(
+                    f"[{u.get('id', '')}] {u.get('content', '')}"
+                    for u in units[:6]
+                )
+        except Exception as exc:
+            logger.warning("quiz_generator: wiki retrieval failed (%s), continuing without context", exc)
+
+    if not context:
+        context = "(Không có ngữ cảnh từ kho tri thức — tự tạo câu hỏi dựa trên trọng tâm)"
+
+    prompt = _PROMPT_TMPL.format(
+        focus=week_focus,
+        tasks="\n".join(f"- {t}" for t in week_tasks),
+        context=context,
+        n=n,
+    )
+
+    settings = get_settings()
+    try:
+        response = await call_with_retry(
+            client,
+            model=settings.default_model,
+            max_tokens=4000,
+            messages=[
+                {"role": "system", "content": _SYSTEM},
+                {"role": "user", "content": prompt},
+            ],
+        )
+        raw = _extract_json(response.choices[0].message.content or "{}")
+        data = json.loads(raw)
+        questions = data.get("questions", [])
+        # bloom_level is optional for backward compatibility
+        questions = [
+            q for q in questions
+            if isinstance(q.get("stem"), str)
+            and isinstance(q.get("choices"), list)
+            and len(q["choices"]) == 4
+            and isinstance(q.get("correct_index"), int)
+        ]
+        questions = await _review_and_patch(client, questions, settings)
+        questions = _validate_structure(questions)
+        questions = _shuffle_answer_position(questions)
+        return questions
+    except Exception as exc:
+        logger.error("quiz_generator: generation failed: %s", exc)
+        raise

backend/app/math_wiki/agents/reranker.py

@@ -0,0 +1,43 @@
+import json
+import logging
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+from app.math_wiki.prompts import MODE_PROMPTS
+from app.math_wiki.utils import _extract_json
+from app.math_wiki.schemas import WikiUnit
+
+logger = logging.getLogger(__name__)
+
+
+async def rerank(client: AsyncOpenAI, query: str, candidates: list[WikiUnit]) -> list[str]:
+    settings = get_settings()
+    candidate_input = [
+        {"id": u.id, "type": u.type, "content": u.content}
+        for u in candidates
+    ]
+    payload = json.dumps({"query": query, "candidates": candidate_input})
+    response = await call_with_retry(
+        client,
+        model=settings.default_model,
+        messages=[
+            {"role": "system", "content": MODE_PROMPTS["RERANK"]},
+            {"role": "user", "content": payload},
+        ],
+        max_tokens=200,
+    )
+    content = _extract_json(response.choices[0].message.content or "{}")
+    try:
+        parsed = json.loads(content)
+    except json.JSONDecodeError:
+        parsed = {}
+    top_ids: list[str] = parsed.get("top_ids", [])
+
+    valid_ids = {u.id for u in candidates}
+    filtered = [uid for uid in top_ids if uid in valid_ids]
+    if len(filtered) < len(top_ids):
+        logger.warning(
+            "Reranker returned %d unknown ID(s), filtered out",
+            len(top_ids) - len(filtered),
+        )
+    return filtered[:5]

backend/app/math_wiki/agents/reviewer.py

@@ -0,0 +1,75 @@
+import json
+import logging
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+from app.math_wiki.prompts import MODE_PROMPTS
+from app.math_wiki.utils import _extract_json
+from app.math_wiki.schemas import WikiUnit, ReviewOutput
+
+logger = logging.getLogger(__name__)
+
+_VALID_VERDICTS = {"correct", "partial", "incorrect"}
+
+
+def _is_inconsistent(parsed: dict) -> bool:
+    """Return True when verdict is non-correct but all explanatory fields are empty."""
+    if parsed.get("verdict") == "correct":
+        return False
+    has_errors = bool([e for e in parsed.get("errors", []) if str(e).strip()])
+    has_feedback = bool(str(parsed.get("feedback", "")).strip())
+    return not has_errors and not has_feedback
+
+
+async def _call_reviewer(client: AsyncOpenAI, messages: list, settings) -> dict:
+    response = await call_with_retry(
+        client,
+        model=settings.default_model,
+        messages=messages,
+        max_tokens=2048,
+    )
+    content = _extract_json(response.choices[0].message.content or "{}")
+    try:
+        return json.loads(content)
+    except json.JSONDecodeError:
+        raise ValueError("Review agent returned malformed JSON")
+
+
+async def review_solution(
+    client: AsyncOpenAI,
+    problem: str,
+    solution: str,
+    context: list[WikiUnit],
+) -> ReviewOutput:
+    settings = get_settings()
+    payload = (
+        json.dumps({
+            "problem": problem,
+            "solution": solution,
+            "context": [{"id": u.id, "content": u.content} for u in context],
+        })
+        + "\n\nRespond with ONLY a JSON object. No prose or markdown."
+    )
+    messages = [
+        {"role": "system", "content": MODE_PROMPTS["REVIEW"]},
+        {"role": "user", "content": payload},
+    ]
+
+    parsed = await _call_reviewer(client, messages, settings)
+
+    if _is_inconsistent(parsed):
+        logger.warning("Reviewer returned inconsistent response (non-correct with no errors/feedback) — retrying")
+        parsed = await _call_reviewer(client, messages, settings)
+
+    verdict = parsed.get("verdict", "incorrect")
+    if verdict not in _VALID_VERDICTS:
+        verdict = "incorrect"
+
+    return ReviewOutput(
+        verdict=verdict,
+        score=str(parsed.get("score", "0/10")),
+        correct_steps=[str(s) for s in parsed.get("correct_steps", []) if str(s).strip()],
+        errors=[str(e) for e in parsed.get("errors", []) if str(e).strip()],
+        feedback=str(parsed.get("feedback", "")),
+        correct_approach=str(parsed.get("correct_approach", "")),
+    )

backend/app/math_wiki/agents/solver.py

@@ -0,0 +1,362 @@
+import json
+import re
+import logging
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+from app.math_wiki.prompts import MODE_PROMPTS
+from app.math_wiki.utils import _extract_json, InsufficientKnowledgeError, VALID_CONFIDENCE
+from app.math_wiki.schemas import WikiUnit, SolverOutput
+
+logger = logging.getLogger(__name__)
+
+# Bare slug/ID with no whitespace — not a human-readable step
+_SLUG_RE = re.compile(r'^[\w-]+$')
+_BUOC_RE = re.compile(r'^Bước\s+\d+\s*:', re.UNICODE)
+_PHAN_RE = re.compile(r'^\*\*Phần\s+[a-dA-D]', re.UNICODE)  # multi-part section headers
+
+_EXPECTED_KEYS = {"problem_type", "steps", "final_answer", "confidence", "used_knowledge_ids"}
+
+
+def _inject_buoc_prefix(steps: list[str]) -> list[str]:
+    """Ensure every non-header step starts with 'Bước N: '.
+
+    The SOLVE prompt requires this format but the model often skips it for
+    simple problems. Post-processing guarantees format compliance without
+    changing any mathematical content.
+    """
+    result: list[str] = []
+    n = 0
+    for step in steps:
+        s = step.strip()
+        if not s:
+            continue
+        # Section headers (multi-part) and already-prefixed steps pass through unchanged
+        if _PHAN_RE.match(s) or _BUOC_RE.match(s):
+            if not _PHAN_RE.match(s):
+                n += 1  # count prefixed steps so subsequent injections are sequential
+            result.append(s)
+        else:
+            n += 1
+            result.append(f"Bước {n}: {s}")
+    return result
+
+
+def _safe_parse_literal(s: str):
+    """Parse a Python-style literal string using json.loads only (no ast.literal_eval).
+    Single quotes are normalized to double quotes as a best-effort step."""
+    try:
+        return json.loads(s)
+    except json.JSONDecodeError:
+        pass
+    try:
+        return json.loads(s.replace("'", '"'))
+    except json.JSONDecodeError:
+        return None
+
+
+def _normalize(parsed: dict, valid_ids: set[str], _label_hint: str = "") -> SolverOutput:
+    """Map whatever JSON structure the model returns into SolverOutput fields."""
+
+    # Model sometimes wraps the response in a single top-level key (e.g. {"proof": {...}}).
+    # Unwrap when none of the expected keys are present at the top level.
+    if parsed and not (_EXPECTED_KEYS & parsed.keys()):
+        inner = next(iter(parsed.values()))
+        if isinstance(inner, dict):
+            parsed = inner
+
+    # Multi-part problems: model may return {"parts": [{"label": "a", "steps": [...], "final_answer": "..."}]}
+    # Fold into the flat schema: part headers injected into steps, combined final_answer "a) X; b) Y".
+    raw_parts = parsed.get("parts")
+    if isinstance(raw_parts, list) and raw_parts and isinstance(raw_parts[0], dict):
+        combined_steps: list[str] = []
+        combined_answers: list[str] = []
+        for part in raw_parts:
+            label = str(part.get("label", "")).strip().rstrip(")")
+            header = f"**Phần {label})**" if label else None
+            if header:
+                combined_steps.append(header)
+            part_steps = part.get("steps", [])
+            if isinstance(part_steps, list):
+                combined_steps.extend(str(s) for s in part_steps if str(s).strip())
+            fa = str(part.get("final_answer", part.get("answer", ""))).strip()
+            if fa:
+                prefix = f"{label}) " if label else ""
+                combined_answers.append(f"{prefix}{fa}")
+        if combined_answers:
+            parsed = dict(parsed)
+            parsed["steps"] = combined_steps
+            parsed["final_answer"] = "; ".join(combined_answers)
+            parsed.pop("parts", None)
+
+    # --- steps ---
+    def _step_to_str(s) -> str:
+        if isinstance(s, str):
+            # Slug-like strings (no whitespace) are leaked wiki IDs, not steps
+            if _SLUG_RE.match(s):
+                return ""
+            return s
+        if isinstance(s, dict):
+            # Model returned {"step": N, "description"/"action"/"detail": "...", "result": "..."}
+            desc = str(s.get("description") or s.get("action") or s.get("statement")
+                    or s.get("detail") or s.get("work") or s.get("explanation") or "")
+            result = str(s.get("result") or "")
+            if not desc:
+                # Collect string values; for nested dicts, recurse one level deep
+                parts = []
+                for k, v in s.items():
+                    if k == "step":
+                        continue
+                    if isinstance(v, str) and v.strip():
+                        parts.append(v)
+                    elif isinstance(v, dict):
+                        parts.append(_step_to_str(v))
+                desc = " ".join(p for p in parts if p)
+            if desc and result and result not in desc:
+                return f"{desc} → {result}"
+            return desc or result or str(s)
+        return str(s)
+
+    steps: list[str] = []
+    if isinstance(parsed.get("steps"), list):
+        steps = [_step_to_str(s) for s in parsed["steps"]]
+    elif isinstance(parsed.get("solution"), dict):
+        sol = parsed["solution"]
+        if isinstance(sol.get("steps"), list):
+            steps = [_step_to_str(s) for s in sol["steps"]]
+    if not steps:
+        for key in ("work", "explanation", "method"):
+            if val := parsed.get(key):
+                steps = [str(val)]
+                break
+    # Drop empty strings AND slug-like tokens regardless of how they were produced
+    steps = [s for s in steps if s.strip() and not _SLUG_RE.match(s.strip())]
+
+    # --- final_answer ---
+    _SIMPLE_VAR = re.compile(r'^[a-zA-Z_]\w{0,3}$')  # x, y, x1, y_0 — short math vars only
+
+    def _dict_to_str(d: dict) -> str:
+        """Convert a dict final_answer to a readable string.
+        Simple variable keys (x, y) → $x = 3$; Vietnamese/long keys → plain "key: value"."""
+        parts = []
+        for k, v in d.items():
+            k_str = str(k).replace("_", " ")
+            v_str = str(v)
+            if _SIMPLE_VAR.match(str(k)):
+                parts.append(f"${k_str} = {v_str}$")
+            else:
+                parts.append(f"{k_str}: {v_str}")
+        return " và ".join(parts) if parts else ""
+
+    def _coerce_final(val) -> str:
+        if isinstance(val, dict):
+            return _dict_to_str(val)
+        s = str(val)
+        # Model returned a Python dict repr string like "{'x': 3, 'y': 2}"
+        if s.startswith("{") and s.endswith("}"):
+            parsed_val = _safe_parse_literal(s)
+            if isinstance(parsed_val, dict):
+                return _dict_to_str(parsed_val)
+        return s
+
+    final_answer: str = ""
+    for key in ("final_answer", "answer"):
+        if val := parsed.get(key):
+            final_answer = _coerce_final(val)
+            break
+    if not final_answer:
+        sol = parsed.get("solution")
+        if isinstance(sol, str):
+            final_answer = sol
+        elif isinstance(sol, dict):
+            inner = sol.get("answer") or sol.get("result") or sol.get("conclusion") or sol.get("summary")
+            if inner:
+                final_answer = _coerce_final(inner)
+            else:
+                # Try solution.results (e.g. {"cuc_dai": {"x": -1, "y": 10}, ...})
+                results = sol.get("results")
+                if isinstance(results, dict):
+                    parts = []
+                    for k, v in results.items():
+                        k_label = str(k).replace("_", " ")
+                        v_str = _dict_to_str(v) if isinstance(v, dict) else str(v)
+                        parts.append(f"{k_label}: {v_str}")
+                    final_answer = "; ".join(parts)
+                # Don't call _dict_to_str(sol) — that formats steps+results together which is ugly
+    if not final_answer:
+        for key in ("roots", "solutions", "result", "x"):
+            if val := parsed.get(key):
+                final_answer = str(val)
+                break
+    # Proof-mode fallbacks: model may use "statement" or "conclusion" instead of "final_answer"
+    if not final_answer:
+        for key in ("statement", "conclusion", "summary"):
+            if val := parsed.get(key):
+                final_answer = str(val)
+                if not final_answer.rstrip().endswith("∎"):
+                    final_answer = final_answer.rstrip() + " ∎"
+                break
+
+    # Last-resort catch-all: model used completely non-standard keys.
+    if not final_answer:
+        # 1. If steps were extracted, use the last step as final_answer.
+        if steps:
+            final_answer = steps[-1]
+            logger.warning("Derived final_answer from last step (keys: %s)", list(parsed.keys()))
+        else:
+            # 2. Collect string values; use them as steps + answer.
+            all_vals = [str(v) for v in parsed.values() if isinstance(v, str) and str(v).strip()]
+            if all_vals:
+                steps = all_vals
+                final_answer = all_vals[-1]
+                logger.warning("Used string catch-all for keys: %s", list(parsed.keys()))
+            else:
+                # 3. Format list-of-dict values (e.g. extrema, roots) into a readable string.
+                for v in parsed.values():
+                    if isinstance(v, list) and v and isinstance(v[0], dict):
+                        parts = []
+                        for item in v:
+                            parts.append(", ".join(f"{k} = {val}" for k, val in item.items()))
+                        final_answer = "; ".join(parts)
+                        steps = [final_answer]
+                        logger.warning("Formatted list-of-dict value for keys: %s", list(parsed.keys()))
+                        break
+
+    # Guard: model returned a list (JSON array or Python literal) instead of a formatted string.
+    # Reformat as human-readable "x = a hoặc x = b" — the validator still flags
+    # ODE cases where roots ≠ general solution.
+    if final_answer and final_answer.lstrip().startswith('['):
+        parsed_fa = _safe_parse_literal(final_answer)
+        if isinstance(parsed_fa, list) and parsed_fa:
+            raw_items = [str(v) for v in parsed_fa]
+
+            def _has_equation(v: str) -> bool:
+                inner = v.strip()
+                if inner.startswith('$') and inner.endswith('$'):
+                    inner = inner[1:-1]
+                return '=' in inner
+
+            parts = [item if _has_equation(item) else f"x = {item}" for item in raw_items]
+            final_answer = parts[0] if len(parts) == 1 else " hoặc ".join(parts)
+            logger.warning("Reformatted list final_answer to: %r", final_answer)
+
+    # --- problem_type ---
+    _LABEL_VI = {
+        "algebra": "đại số", "geometry": "hình học", "calculus": "giải tích",
+        "trigonometry": "lượng giác", "statistics": "thống kê", "probability": "xác suất",
+        "combinatorics": "tổ hợp", "number_theory": "số học",
+        "complex_numbers": "số phức", "sequences": "dãy số",
+        "vectors": "vectơ", "functions": "hàm số",
+    }
+    _raw_pt = str(parsed.get("problem_type", parsed.get("method", "")))
+    if _raw_pt:
+        problem_type = _raw_pt
+    else:
+        problem_type = _LABEL_VI.get(_label_hint, _label_hint or "đại số")
+
+    # --- used_knowledge_ids — keep only IDs that actually exist in context ---
+    raw_ids = parsed.get("used_knowledge_ids", [])
+    if not isinstance(raw_ids, list):
+        raw_ids = []
+    used_ids = [uid for uid in raw_ids if uid in valid_ids]
+
+    # --- confidence ---
+    confidence = str(parsed.get("confidence", "medium"))
+    if confidence not in VALID_CONFIDENCE:
+        confidence = "medium"
+
+    if not final_answer:
+        raise InsufficientKnowledgeError("Solver returned no answer")
+    if final_answer.strip().upper() == "INSUFFICIENT_KNOWLEDGE":
+        raise InsufficientKnowledgeError("Solver indicated insufficient knowledge")
+
+    # Warn when final_answer is not mentioned in any step — likely a commit-before-compute error.
+    # Skip for multi-part answers (format "a) X; b) Y") — the combined string won't appear verbatim.
+    _is_multipart = bool(re.match(r'^[a-dA-D]\)', final_answer.strip()))
+    if steps and not _is_multipart and not any(final_answer.lower()[:20] in s.lower() for s in steps):
+        logger.warning(
+            "final_answer %r not found in steps — possible answer/step mismatch", final_answer
+        )
+
+    if not steps:
+        logger.warning("solver: no parseable steps in response — using final_answer as sole step. raw=%r", str(parsed)[:200])
+
+    final_steps = _inject_buoc_prefix(steps or [final_answer])
+
+    return SolverOutput(
+        problem_type=problem_type,
+        used_knowledge_ids=used_ids,
+        steps=final_steps,
+        final_answer=final_answer,
+        confidence=confidence,
+    )
+
+
+async def solve(
+    client: AsyncOpenAI,
+    problem_text: str,
+    context: list[WikiUnit],
+    label: str = "",
+    prior_failure: str | None = None,
+) -> SolverOutput:
+    settings = get_settings()
+    payload = json.dumps({
+        "problem": problem_text,
+        "context": [{"id": u.id, "type": u.type, "content": u.content} for u in context],
+    })
+    if prior_failure:
+        payload += f"\n\n⚠ Lưu ý từ lần giải trước: {prior_failure}"
+    payload += "\n\nRespond with ONLY a JSON object. No prose or markdown."
+    response = await call_with_retry(
+        client,
+        model=settings.default_model,
+        messages=[
+            {"role": "system", "content": MODE_PROMPTS["SOLVE"]},
+            {"role": "user", "content": payload},
+        ],
+        max_tokens=4096,
+    )
+    content = _extract_json(response.choices[0].message.content or "{}")
+    try:
+        parsed = json.loads(content)
+    except json.JSONDecodeError:
+        # Truncated response — retry without context payload (shorter prompt, better chance)
+        logger.warning("Solver response truncated; retrying without context")
+        bare_payload = (
+            json.dumps({"problem": problem_text, "context": []})
+            + "\n\nRespond with ONLY a JSON object. No prose or markdown."
+        )
+        retry_response = await call_with_retry(
+            client,
+            model=settings.default_model,
+            messages=[
+                {"role": "system", "content": MODE_PROMPTS["SOLVE"]},
+                {"role": "user", "content": bare_payload},
+            ],
+            max_tokens=4096,
+        )
+        retry_content = _extract_json(retry_response.choices[0].message.content or "{}")
+        try:
+            parsed = json.loads(retry_content)
+        except json.JSONDecodeError:
+            raise InsufficientKnowledgeError("Malformed solver response")
+    valid_ids = {u.id for u in context}
+    result = _normalize(parsed, valid_ids, _label_hint=label)
+
+    # Guard: if final_answer echoes the problem (starts with an imperative verb and overlaps
+    # significantly with the question), replace it with the last non-trivial step.
+    _STARTERS = ("tìm ", "cho ", "tính ", "giải ", "chứng ", "hãy ", "biết ", "xét ")
+    fa_lower = result.final_answer.lower().strip()
+    pt_lower = problem_text.lower()
+    if (any(fa_lower.startswith(s) for s in _STARTERS)
+            and pt_lower[:40] in fa_lower):
+        candidate = next(
+            (s for s in reversed(result.steps)
+             if s.strip() and not any(s.lower().strip().startswith(st) for st in _STARTERS)),
+            None,
+        )
+        if candidate:
+            logger.warning("final_answer resembled the question — substituted last useful step")
+            result = result.model_copy(update={"final_answer": candidate})
+
+    return result

backend/app/math_wiki/agents/sympy_verifier.py

@@ -0,0 +1,274 @@
+"""Deterministic symbolic verification of math solutions using SymPy.
+
+Returns (True, []) on confirmed correct, (False, [issues]) on confirmed wrong,
+(None, []) when inconclusive (parse failure, proof/geometry/combinatorics, etc.).
+Never raises — all exceptions produce (None, []) to avoid false negatives.
+"""
+from __future__ import annotations
+import logging
+import re
+
+logger = logging.getLogger(__name__)
+
+# Topics where symbolic substitution doesn't apply.
+_SKIP_TYPES = frozenset({
+    "chứng minh", "proof", "geometry", "hình học",
+    "combinatorics", "tổ hợp", "statistics", "thống kê",
+    "probability", "xác suất", "number_theory", "số học",
+})
+
+
+def _should_skip(problem_type: str) -> bool:
+    pt = problem_type.lower()
+    return any(s in pt for s in _SKIP_TYPES)
+
+
+# ── answer parsing ────────────────────────────────────────────────────────────
+
+def _parse_candidates(final_answer: str) -> list[str]:
+    """Extract individual candidate value strings from a final_answer string.
+
+    Handles forms like:
+      "x = 2 hoặc x = 3"   → ["2", "3"]
+      "$x = 2$ hoặc $x = 3$"  → ["2", "3"]
+      "x = 2"              → ["2"]
+      "x1 = 1, x2 = -1"   → ["1", "-1"]
+    Returns raw value strings to be parsed by SymPy.
+    """
+    # Strip LaTeX delimiters
+    text = re.sub(r'\$', '', final_answer)
+    # Split on Vietnamese "hoặc", commas, semicolons, or "or"
+    parts = re.split(r'\bhoặc\b|\bor\b|[,;]', text, flags=re.IGNORECASE)
+    values: list[str] = []
+    for part in parts:
+        part = part.strip()
+        # Look for "var = value" pattern
+        m = re.search(r'=\s*(.+)$', part)
+        if m:
+            values.append(m.group(1).strip())
+    return values
+
+
+def _parse_system_assignments(final_answer: str) -> dict[str, str] | None:
+    """Parse 'x = a, y = b' style system answers into {var: value} dict."""
+    text = re.sub(r'\$', '', final_answer)
+    parts = re.split(r'\bvà\b|\band\b|[,;]', text, flags=re.IGNORECASE)
+    assignments: dict[str, str] = {}
+    for part in parts:
+        part = part.strip()
+        m = re.match(r'^([a-zA-Z]\w*)\s*=\s*(.+)$', part)
+        if m:
+            assignments[m.group(1).strip()] = m.group(2).strip()
+    return assignments if len(assignments) >= 2 else None
+
+
+def _extract_ode_solution(final_answer: str):
+    """Extract y = f(x) from an ODE general solution string.
+    Returns a SymPy expression for f(x), or None on failure."""
+    try:
+        import sympy as sp
+        text = re.sub(r'\$', '', final_answer).strip()
+        # Match "y = ..." at start of answer
+        m = re.match(r'y\s*=\s*(.+)', text, re.IGNORECASE)
+        if not m:
+            return None
+        expr_str = m.group(1).strip()
+        # Replace C1, C2 constants with SymPy symbols
+        expr_str = re.sub(r'\bC_?(\d+)\b', r'C\1', expr_str)
+        x, C1, C2, C3 = sp.symbols('x C1 C2 C3')
+        local_dict = {
+            'x': x, 'C1': C1, 'C2': C2, 'C3': C3,
+            'e': sp.E, 'pi': sp.pi, 'sin': sp.sin, 'cos': sp.cos,
+            'exp': sp.exp, 'ln': sp.ln, 'sqrt': sp.sqrt,
+        }
+        return sp.sympify(expr_str, locals=local_dict)
+    except Exception:
+        return None
+
+
+def _strip_prose(s: str) -> str:
+    """Strip leading prose words from a potential math expression."""
+    m = re.search(r'[0-9x\(\-\+\*\/\^\.]', s)
+    return s[m.start():] if m else s
+
+
+# ── verification routines ─────────────────────────────────────────────────────
+
+def _verify_equation(problem_text: str, candidate_values: list[str]) -> tuple[bool | None, list[str]]:
+    """Substitute each candidate into the equation extracted from problem_text."""
+    try:
+        import sympy as sp
+        text = re.sub(r'\$', '', problem_text)
+        x = sp.Symbol('x')
+        local = {'x': x, 'sqrt': sp.sqrt, 'abs': sp.Abs, 'log': sp.log, 'ln': sp.ln}
+
+        # Try each "lhs = rhs" match; skip those whose lhs won't sympify
+        expr = None
+        for eq_match in re.finditer(r'([^:=\n]+)=([^:=\n]+)', text):
+            lhs_raw = _strip_prose(eq_match.group(1).strip())
+            rhs_raw = eq_match.group(2).strip()
+            try:
+                lhs = sp.sympify(lhs_raw, locals=local)
+                rhs = sp.sympify(rhs_raw, locals=local)
+                expr = lhs - rhs
+                break
+            except Exception:
+                continue
+
+        if expr is None:
+            return None, []
+
+        issues: list[str] = []
+        valid_count = 0
+        for val_str in candidate_values:
+            try:
+                val = sp.sympify(val_str, locals={'sqrt': sp.sqrt})
+                residual = sp.simplify(expr.subs(x, val))
+                if residual == 0:
+                    valid_count += 1
+                else:
+                    issues.append(f"x = {val_str} does not satisfy the equation (residual = {residual})")
+            except Exception:
+                return None, []  # can't evaluate — inconclusive
+
+        if issues:
+            return False, issues
+        if valid_count > 0:
+            return True, []
+        return None, []
+    except Exception as exc:
+        logger.debug("_verify_equation failed: %s", exc)
+        return None, []
+
+
+def _verify_system(problem_text: str, assignments: dict[str, str]) -> tuple[bool | None, list[str]]:
+    """Substitute variable assignments into all equations in problem_text."""
+    try:
+        import sympy as sp
+        text = re.sub(r'\$', '', problem_text)
+        # Split on conjunctions first so each clause is a single equation candidate
+        clauses = re.split(r'\bvà\b|\band\b|[;\n]', text, flags=re.IGNORECASE)
+
+        syms = {v: sp.Symbol(v) for v in assignments}
+        local = {**syms, 'sqrt': sp.sqrt, 'abs': sp.Abs}
+
+        val_map = {}
+        for var, val_str in assignments.items():
+            try:
+                val_map[syms[var]] = sp.sympify(val_str, locals=local)
+            except Exception:
+                return None, []
+
+        issues: list[str] = []
+        checked = 0
+        for clause in clauses[:4]:  # limit to first 4 clauses
+            if '=' not in clause:
+                continue
+            parts = clause.split('=', 1)
+            if len(parts) != 2:
+                continue
+            try:
+                lhs = sp.sympify(_strip_prose(parts[0].strip()), locals=local)
+                rhs = sp.sympify(parts[1].strip(), locals=local)
+                residual = sp.simplify((lhs - rhs).subs(val_map))
+                checked += 1
+                if residual != 0:
+                    issues.append(f"Assignment {assignments} does not satisfy equation '{clause.strip()}'")
+            except Exception:
+                continue
+
+        if not checked:
+            return None, []
+        return (False, issues) if issues else (True, [])
+    except Exception as exc:
+        logger.debug("_verify_system failed: %s", exc)
+        return None, []
+
+
+def _verify_ode(problem_text: str, solution_expr) -> tuple[bool | None, list[str]]:
+    """Differentiate the proposed solution and substitute into the ODE."""
+    try:
+        import sympy as sp
+        text = re.sub(r'\$', '', problem_text)
+        # Extract ODE — look for y'' / y' notation and convert
+        ode_match = re.search(r"y[''′]+[^=\n]*=[^\n]+", text)
+        if not ode_match:
+            return None, []
+
+        x = sp.Symbol('x')
+        y_fn = sp.Function('y')
+        y = solution_expr  # already a SymPy expression in x
+
+        ode_str = ode_match.group(0)
+        # Replace y'', y' with computed derivatives
+        d2y = sp.diff(y, x, 2)
+        dy = sp.diff(y, x)
+
+        # Build ODE expression by substituting into string-parsed version
+        ode_expr_str = (
+            ode_str
+            .replace("y''", f"({d2y})")
+            .replace("y'",  f"({dy})")
+            .replace("y",   f"({y})")
+        )
+        parts = ode_expr_str.split('=', 1)
+        if len(parts) != 2:
+            return None, []
+
+        local = {'x': x, 'exp': sp.exp, 'sin': sp.sin, 'cos': sp.cos,
+                 'sqrt': sp.sqrt, 'ln': sp.ln, 'C1': sp.Symbol('C1'),
+                 'C2': sp.Symbol('C2'), 'C3': sp.Symbol('C3')}
+        lhs = sp.sympify(parts[0].strip(), locals=local)
+        rhs = sp.sympify(parts[1].strip(), locals=local)
+        residual = sp.simplify(lhs - rhs)
+        if residual == 0:
+            return True, []
+        return False, [f"Proposed ODE solution does not satisfy the equation (residual = {residual})"]
+    except Exception as exc:
+        logger.debug("_verify_ode failed: %s", exc)
+        return None, []
+
+
+# ── public API ────────────────────────────────────────────────────────────────
+
+def sympy_verify(
+    problem_text: str,
+    final_answer: str,
+    problem_type: str = "",
+) -> tuple[bool | None, list[str]]:
+    """Verify final_answer against problem_text symbolically.
+
+    Returns:
+        (True,  [])       — confirmed correct
+        (False, [issues]) — confirmed wrong
+        (None,  [])       — inconclusive (proof, geometry, parse failure, etc.)
+    """
+    try:
+        if _should_skip(problem_type):
+            return None, []
+
+        # Multi-part answer ("a) X; b) Y") — can't verify symbolically without splitting the problem
+        if re.match(r'^[a-dA-D]\)', final_answer.strip()):
+            return None, []
+
+        # ODE path: problem_type contains "vi phân" or "ode" and answer has y =
+        is_ode = any(k in problem_type.lower() for k in ("vi phân", "ode", "differential"))
+        if is_ode or "y = " in final_answer.lower():
+            sol = _extract_ode_solution(final_answer)
+            if sol is not None:
+                return _verify_ode(problem_text, sol)
+
+        # System of equations: answer has multiple var=val pairs
+        assignments = _parse_system_assignments(final_answer)
+        if assignments:
+            return _verify_system(problem_text, assignments)
+
+        # Single/multiple roots
+        candidates = _parse_candidates(final_answer)
+        if candidates:
+            return _verify_equation(problem_text, candidates)
+
+        return None, []
+    except Exception as exc:
+        logger.debug("sympy_verify top-level exception: %s", exc)
+        return None, []

backend/app/math_wiki/agents/validator.py

@@ -0,0 +1,59 @@
+import json
+import logging
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+from app.math_wiki.prompts import MODE_PROMPTS
+from app.math_wiki.utils import _extract_json
+from app.math_wiki.schemas import WikiUnit, SolverOutput, ValidationResult
+from app.math_wiki.agents.sympy_verifier import sympy_verify
+
+logger = logging.getLogger(__name__)
+
+
+async def validate(
+    client: AsyncOpenAI,
+    solver_output: SolverOutput,
+    context: list[WikiUnit],
+    problem_text: str = "",
+) -> ValidationResult:
+    settings = get_settings()
+    solver_dict = {
+        "problem_type": solver_output.problem_type,
+        "steps": solver_output.steps,
+        "final_answer": solver_output.final_answer,
+        "confidence": solver_output.confidence,
+    }
+    payload = json.dumps({
+        "solver_output": solver_dict,
+        "context": [u.model_dump() for u in context],
+    })
+    response = await call_with_retry(
+        client,
+        model=settings.default_model,
+        messages=[
+            {"role": "system", "content": MODE_PROMPTS["VALIDATE"]},
+            {"role": "user", "content": payload},
+        ],
+        max_tokens=600,
+    )
+    content = _extract_json(response.choices[0].message.content or "{}")
+    try:
+        parsed = json.loads(content)
+    except json.JSONDecodeError:
+        logger.warning("Validator returned malformed JSON — skipping UI issue")
+        return ValidationResult(valid=False, issues=[])
+    llm_result = ValidationResult(**parsed)
+
+    # Deterministic override: if SymPy confirms the answer is wrong, trust it over LLM.
+    if problem_text:
+        sympy_valid, sympy_issues = sympy_verify(
+            problem_text=problem_text,
+            final_answer=solver_output.final_answer,
+            problem_type=solver_output.problem_type,
+        )
+        if sympy_valid is False:
+            logger.debug("SymPy overrides LLM validation — issues: %s", sympy_issues)
+            return ValidationResult(valid=False, issues=llm_result.issues + sympy_issues)
+
+    return llm_result

backend/app/math_wiki/autoirt.py

@@ -0,0 +1,74 @@
+"""AutoIRT: data-driven IRT parameter recalibration from response logs.
+
+Uses MLE to estimate irt_a (discrimination) and irt_b (difficulty) from
+accumulated solution_logs responses. Requires minimum 50 responses per question.
+irt_c (guessing) is fixed at 0.25 for MCQ (4 choices).
+"""
+import logging
+import math
+
+logger = logging.getLogger(__name__)
+
+_MIN_RESPONSES = 50
+_GUESSING = 0.25
+
+
+def _irt_prob(theta: float, a: float, b: float, c: float = _GUESSING) -> float:
+    """3PL IRT probability of correct response."""
+    return c + (1 - c) / (1 + math.exp(-a * (theta - b)))
+
+
+def _mle_difficulty(correct: int, total: int, a: float = 1.0, c: float = _GUESSING) -> float:
+    """Simple MLE estimate of irt_b given observed proportion correct."""
+    if total == 0:
+        return 0.0
+    p = max(c + 0.01, min(0.99, correct / total))
+    # Invert 3PL: b = theta - (1/a) * log((p-c)/(1-p))
+    try:
+        b = -(1 / a) * math.log((p - c) / (1 - p))
+    except (ValueError, ZeroDivisionError):
+        b = 0.0
+    return round(max(-3.0, min(3.0, b)), 2)
+
+
+def _mle_discrimination(correct: int, total: int, irt_b: float) -> float:
+    """Estimate irt_a from point-biserial correlation proxy."""
+    if total < _MIN_RESPONSES:
+        return 1.0
+    p = correct / total
+    if p <= 0 or p >= 1:
+        return 1.0
+    # Bock's approximation: a ∝ p(1-p) / phi(b)
+    phi_b = math.exp(-irt_b ** 2 / 2) / math.sqrt(2 * math.pi)
+    if phi_b < 0.001:
+        return 1.0
+    a = (p * (1 - p)) / phi_b
+    return round(max(0.5, min(3.0, a)), 2)
+
+
+async def run_recalibration(pool) -> dict:
+    """Recalibrate IRT params for all questions with ≥50 responses."""
+    rows = await pool.fetch("""
+        SELECT sl.problem_id,
+               COUNT(*) as total,
+               SUM(CASE WHEN sl.actual_correct = 1 THEN 1 ELSE 0 END) as correct
+        FROM solution_logs sl
+        WHERE sl.problem_id IS NOT NULL AND sl.actual_correct IS NOT NULL
+        GROUP BY sl.problem_id
+        HAVING total >= ?
+    """, _MIN_RESPONSES)
+
+    if not rows:
+        return {"recalibrated": 0, "message": f"No questions with ≥{_MIN_RESPONSES} responses yet"}
+
+    updated = 0
+    for row in rows:
+        irt_b = _mle_difficulty(row["correct"], row["total"])
+        irt_a = _mle_discrimination(row["correct"], row["total"], irt_b)
+        await pool.execute(
+            "UPDATE problems SET irt_a = ?, irt_b = ? WHERE problem_id = ?",
+            irt_a, irt_b, row["problem_id"],
+        )
+        updated += 1
+
+    return {"recalibrated": updated, "min_responses_threshold": _MIN_RESPONSES}

backend/app/math_wiki/bobcat.py

@@ -0,0 +1,85 @@
+"""BOBCAT: Bilevel Optimization-Based CAT (data-gated).
+
+Reference: arXiv 2108.07386, IJCAI 2021
+GitHub: github.com/arghosh/BOBCAT
+
+This module provides the BOBCAT question selection policy as a drop-in
+replacement for MaxInformationSelector once sufficient data is available.
+
+DATA GATE: Requires ≥500 completed adaptive exam sessions in exam_sessions table.
+Deploy: Train offline with `python -m app.math_wiki.bobcat_train`, then
+        set BOBCAT_ENABLED=true in environment to activate.
+"""
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+_ENABLED = os.getenv("BOBCAT_ENABLED", "false").lower() == "true"
+_MIN_SESSIONS = 500
+
+_model = None
+
+
+def is_ready() -> bool:
+    """Returns True only when data gate is met and model is loaded."""
+    return _ENABLED and _model is not None
+
+
+def select_next_question(
+    item_params,          # np.ndarray shape (n_items, 4) — [a, b, c, d]
+    administered_items,   # list[int] — indices already administered
+    est_theta: float,     # current ability estimate
+) -> int:
+    """Select next question using BOBCAT policy.
+
+    Falls back to MaxInformationSelector if model not loaded.
+    """
+    if not is_ready():
+        # Graceful degradation: use classical Fisher Information selection
+        try:
+            from catsim.selection import MaxInformationSelector
+            import numpy as np
+            selector = MaxInformationSelector()
+            return int(selector.select(
+                items=item_params,
+                administered_items=np.array(administered_items),
+                est_theta=est_theta,
+            ))
+        except Exception as exc:
+            logger.warning("BOBCAT fallback to MaxInfo failed: %s", exc)
+            # Last resort: pick first un-administered item
+            admin_set = set(administered_items)
+            for i in range(len(item_params)):
+                if i not in admin_set:
+                    return i
+            return 0
+
+    # BOBCAT neural policy (activated when model loaded)
+    try:
+        import torch
+        import numpy as np
+        history_vec = _encode_history(item_params, administered_items, est_theta)
+        with torch.no_grad():
+            scores = _model(torch.tensor(history_vec, dtype=torch.float32).unsqueeze(0))
+            scores = scores.squeeze(0).numpy()
+        # Mask already-administered items
+        admin_set = set(administered_items)
+        for idx in admin_set:
+            scores[idx] = -1e9
+        return int(np.argmax(scores))
+    except Exception as exc:
+        logger.warning("BOBCAT selection failed (%s), falling back", exc)
+        return select_next_question(item_params, administered_items, est_theta)
+
+
+def _encode_history(item_params, administered_items, est_theta: float):
+    """Encode student history as fixed-size input vector for BOBCAT network."""
+    import numpy as np
+    n_items = len(item_params)
+    vec = np.zeros(n_items + 1)
+    for idx in administered_items:
+        if 0 <= idx < n_items:
+            vec[idx] = 1.0
+    vec[-1] = est_theta / 3.0  # normalize theta to [-1, 1] approx
+    return vec

backend/app/math_wiki/cache.py

@@ -0,0 +1,43 @@
+"""LRU semantic cache for retrieval results.
+
+Key: normalized query text hash.
+Value: list of wiki_unit IDs (retrieval result).
+TTL: 1 hour. Max entries: 512.
+"""
+import hashlib
+import logging
+import time
+from collections import OrderedDict
+
+logger = logging.getLogger(__name__)
+
+_MAX_ENTRIES = 512
+_TTL_SECONDS = 3600
+
+_cache: OrderedDict[str, tuple[list[str], float]] = OrderedDict()
+
+
+def _key(query: str) -> str:
+    normalized = " ".join(query.lower().split())
+    return hashlib.sha256(normalized.encode()).hexdigest()[:16]
+
+
+def get(query: str) -> list[str] | None:
+    k = _key(query)
+    entry = _cache.get(k)
+    if entry is None:
+        return None
+    ids, ts = entry
+    if time.time() - ts > _TTL_SECONDS:
+        del _cache[k]
+        return None
+    _cache.move_to_end(k)
+    return ids
+
+
+def put(query: str, ids: list[str]) -> None:
+    k = _key(query)
+    _cache[k] = (ids, time.time())
+    _cache.move_to_end(k)
+    while len(_cache) > _MAX_ENTRIES:
+        _cache.popitem(last=False)

backend/app/math_wiki/context_builder.py

@@ -0,0 +1,41 @@
+"""Ordered context assembly for the math solver.
+
+Orders wiki units: prerequisites → core concept → formulas/theorems → examples → mistakes.
+Caps total serialized content at ~8000 tokens (approx 32000 chars).
+"""
+from app.math_wiki.schemas import WikiUnit
+
+_NODE_ORDER = {
+    "theorem": 1,
+    "formula": 2,
+    "concept": 3,
+    "procedure": 4,
+    "pattern": 5,
+    "example": 6,
+    "mistake": 7,
+}
+_MAX_CHARS = 32_000
+
+
+def _rank(unit: WikiUnit) -> int:
+    node_type = getattr(unit, "node_type", None) or unit.type or "pattern"
+    return _NODE_ORDER.get(node_type, 5)
+
+
+def build_context(units: list[WikiUnit]) -> str:
+    """Serialize wiki units into an ordered context string for the solver prompt."""
+    if not units:
+        return ""
+    ordered = sorted(units, key=_rank)
+    parts = []
+    total = 0
+    for unit in ordered:
+        label = (getattr(unit, "node_type", None) or unit.type or "unit").upper()
+        topic = (unit.topic or "").upper()
+        content = unit.content or ""
+        entry = f"[{label}: {topic}]\n{content}\n---"
+        if total + len(entry) > _MAX_CHARS:
+            break
+        parts.append(entry)
+        total += len(entry)
+    return "\n".join(parts)

backend/app/math_wiki/crag.py

@@ -0,0 +1,57 @@
+"""Corrective RAG scoring gate.
+
+Scores each retrieved candidate against the query using cosine similarity.
+Discards candidates below threshold. If all are discarded, rewrites the query
+and signals a retry.
+"""
+import json
+import logging
+import numpy as np
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+def _cosine(a: list[float], b: list[float]) -> float:
+    va = np.array(a, dtype=np.float32)
+    vb = np.array(b, dtype=np.float32)
+    denom = (np.linalg.norm(va) + 1e-9) * (np.linalg.norm(vb) + 1e-9)
+    return float(np.dot(va, vb) / denom)
+
+
+def score_candidates(
+    query_embedding: list[float],
+    candidates,  # list[WikiUnit]
+    threshold: float | None = None,
+) -> tuple[list, bool]:
+    """Score candidates, filter below threshold.
+
+    Returns (filtered_candidates, should_retry).
+    should_retry=True when ALL candidates were below threshold.
+    """
+    settings = get_settings()
+    t = threshold if threshold is not None else getattr(settings, "crag_threshold", 0.20)
+
+    if not candidates or not query_embedding:
+        return candidates, False
+
+    scored = []
+    for unit in candidates:
+        try:
+            emb = json.loads(unit.embedding) if isinstance(unit.embedding, str) else unit.embedding
+            if emb:
+                score = _cosine(query_embedding, emb)
+                scored.append((score, unit))
+        except Exception:
+            scored.append((0.0, unit))  # keep on parse error
+
+    if not scored:
+        return candidates, False
+
+    above = [(s, u) for s, u in scored if s >= t]
+    if not above:
+        logger.info("CRAG: all %d candidates below threshold %.2f — flagging retry", len(scored), t)
+        return [], True  # signal retry
+
+    above.sort(key=lambda x: x[0], reverse=True)
+    return [u for _, u in above], False

backend/app/math_wiki/deep_cat.py

@@ -0,0 +1,87 @@
+"""Deep CAT with Reinforcement Learning (data-gated).
+
+Reference: arXiv 2502.19275, 2025
+Uses double deep Q-learning for long-term optimal item selection.
+
+DATA GATE: Requires ≥5,000 completed adaptive exam sessions.
+           Current system needs significant user history before training.
+Deploy: Accumulate exam_sessions data, then run offline RL training.
+        Set DEEP_CAT_ENABLED=true to activate once trained.
+"""
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+_ENABLED = os.getenv("DEEP_CAT_ENABLED", "false").lower() == "true"
+_MIN_SESSIONS = 5_000
+
+_q_network = None       # Primary Q-network
+_target_network = None  # Target Q-network (double DQN)
+
+
+def is_ready() -> bool:
+    return _ENABLED and _q_network is not None
+
+
+def select_next_question(
+    state_vector,          # np.ndarray — encoded student state
+    administered_items,    # list[int]
+    n_items: int,
+) -> int:
+    """Select next question via RL Q-network.
+
+    Falls back to BOBCAT → MaxInformationSelector when not ready.
+    """
+    if not is_ready():
+        # Cascade: try BOBCAT first, then MaxInfo
+        try:
+            from app.math_wiki.bobcat import select_next_question as bobcat_select
+            return bobcat_select(
+                item_params=state_vector,
+                administered_items=administered_items,
+                est_theta=0.0,
+            )
+        except Exception:
+            pass
+        # Raw fallback
+        admin_set = set(administered_items)
+        for i in range(n_items):
+            if i not in admin_set:
+                return i
+        return 0
+
+    try:
+        import torch
+        import numpy as np
+        admin_set = set(administered_items)
+        with torch.no_grad():
+            q_values = _q_network(
+                torch.tensor(state_vector, dtype=torch.float32).unsqueeze(0)
+            ).squeeze(0).numpy()
+        q_values[list(admin_set)] = -1e9  # mask administered
+        return int(np.argmax(q_values))
+    except Exception as exc:
+        logger.warning("Deep CAT selection failed (%s), falling back", exc)
+        admin_set = set(administered_items)
+        for i in range(n_items):
+            if i not in admin_set:
+                return i
+        return 0
+
+
+class DQNNetwork:
+    """Placeholder for the Double DQN architecture.
+
+    Architecture (to be implemented during training phase):
+    - Input: state_dim (student history encoded)
+    - Hidden: 2 × 256 ReLU layers
+    - Output: n_items Q-values (one per question)
+
+    Training algorithm:
+    - Replay buffer of (state, action, reward, next_state, done) tuples
+    - Target network updated every 100 steps (Polyak averaging tau=0.005)
+    - Reward: delta in ability estimate accuracy at exam completion
+    - Epsilon-greedy exploration (epsilon decays 1.0 → 0.05 over 10k steps)
+    """
+    pass  # Full implementation added during training phase

backend/app/math_wiki/difficulty_estimator.py

@@ -0,0 +1,61 @@
+"""LLM-based IRT difficulty calibration.
+
+Uses Claude Haiku's self-reported confidence to estimate irt_b (difficulty)
+for each question. Confidence near 1.0 → easy (irt_b negative), near 0 → hard (irt_b positive).
+Mapping: irt_b = (0.5 - confidence) * 4  (range: -2.0 to +2.0)
+"""
+import json
+import logging
+from openai import AsyncOpenAI
+from app.config import get_settings
+from app.agent.core import call_with_retry
+
+logger = logging.getLogger(__name__)
+
+
+async def calibrate_question(client: AsyncOpenAI, problem_id: str, problem_text: str) -> float | None:
+    """Estimate irt_b for a single question. Returns irt_b in range [-2.0, 2.0]."""
+    settings = get_settings()
+    prompt = (
+        f"Giải bài toán sau và đánh giá mức độ tự tin của bạn từ 0.0 đến 1.0:\n\n{problem_text}\n\n"
+        "Trả về JSON: {\"confidence\": 0.8} — chỉ confidence, không giải thích thêm."
+    )
+    try:
+        resp = await call_with_retry(
+            client,
+            model=settings.haiku_model,
+            max_tokens=50,
+            messages=[{"role": "user", "content": prompt}],
+            response_format={"type": "json_object"},
+        )
+        parsed = json.loads(resp.choices[0].message.content or "{}")
+        confidence = float(parsed.get("confidence", 0.5))
+        confidence = max(0.0, min(1.0, confidence))
+        irt_b = round((0.5 - confidence) * 4, 2)
+        logger.debug("Calibrated %s: confidence=%.2f → irt_b=%.2f", problem_id, confidence, irt_b)
+        return irt_b
+    except Exception as exc:
+        logger.warning("calibrate_question failed for %s: %s", problem_id, exc)
+        return None
+
+
+async def run_calibration_job(pool, client: AsyncOpenAI, batch_size: int = 50) -> dict:
+    """Calibrate irt_b for all uncalibrated questions (irt_b == 0.0 and irt_a == 1.0 = default)."""
+    rows = await pool.fetch(
+        "SELECT problem_id, problem_text FROM problems WHERE irt_a = 1.0 AND irt_b = 0.0 LIMIT ?",
+        batch_size,
+    )
+    if not rows:
+        return {"calibrated": 0, "message": "All questions already calibrated"}
+
+    calibrated = 0
+    for row in rows:
+        irt_b = await calibrate_question(client, row["problem_id"], row["problem_text"])
+        if irt_b is not None:
+            await pool.execute(
+                "UPDATE problems SET irt_b = ? WHERE problem_id = ?",
+                irt_b, row["problem_id"],
+            )
+            calibrated += 1
+
+    return {"calibrated": calibrated, "total_remaining": len(rows) - calibrated}

backend/app/math_wiki/dkvmn.py

@@ -0,0 +1,133 @@
+"""DKVMN (Dynamic Key-Value Memory Networks) for knowledge tracing.
+
+This module provides:
+1. The DKVMN PyTorch model class (for offline training)
+2. A predict_mastery() function that reads from concept_mastery/concept_elo tables
+   until a trained model is available.
+
+Training: run `python -m app.math_wiki.dkvmn_train` after accumulating solution_logs data.
+The trained model weights are saved to data/dkvmn_weights.pt.
+"""
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+_MODEL_PATH = os.path.join(os.path.dirname(__file__), "..", "..", "data", "dkvmn_weights.pt")
+_model = None
+_model_loaded = False
+
+# Try to load PyTorch — gracefully degrade if not available
+try:
+    import torch
+    import torch.nn as nn
+    import torch.nn.functional as F
+    _TORCH_AVAILABLE = True
+except ImportError:
+    _TORCH_AVAILABLE = False
+    logger.info("PyTorch not available — DKVMN will use DB mastery fallback")
+
+
+if _TORCH_AVAILABLE:
+    class DKVMN(nn.Module):
+        """Dynamic Key-Value Memory Network for knowledge tracing.
+
+        Architecture:
+        - Key memory: static concept embeddings (n_concepts × key_dim)
+        - Value memory: dynamic knowledge state (memory_size × value_dim)
+        - Input: (question_embed, response) pairs
+        - Output: P(correct) per concept
+        """
+        def __init__(self, n_concepts: int = 50, memory_size: int = 20,
+                     key_dim: int = 50, value_dim: int = 200):
+            super().__init__()
+            self.key_memory = nn.Parameter(torch.randn(memory_size, key_dim))
+            self.value_memory = nn.Parameter(torch.randn(memory_size, value_dim))
+            self.key_embed = nn.Embedding(n_concepts, key_dim)
+            self.erase_linear = nn.Linear(value_dim, value_dim)
+            self.add_linear = nn.Linear(value_dim, value_dim)
+            self.fc_output = nn.Linear(value_dim + key_dim, 1)
+
+        def forward(self, concept_ids: 'torch.Tensor', responses: 'torch.Tensor'):
+            """
+            Args:
+                concept_ids: (batch, seq_len) concept indices
+                responses: (batch, seq_len) 0/1 correctness
+            Returns:
+                predictions: (batch, seq_len) P(correct) for each step
+            """
+            batch_size, seq_len = concept_ids.shape
+            value_mem = self.value_memory.unsqueeze(0).expand(batch_size, -1, -1).clone()
+            predictions = []
+
+            for t in range(seq_len):
+                q_embed = self.key_embed(concept_ids[:, t])  # (batch, key_dim)
+                # Correlation weights
+                w = F.softmax(q_embed @ self.key_memory.T, dim=-1)  # (batch, memory_size)
+                # Read
+                r = (w.unsqueeze(-1) * value_mem).sum(dim=1)  # (batch, value_dim)
+                # Predict
+                pred = torch.sigmoid(self.fc_output(torch.cat([r, q_embed], dim=-1)))
+                predictions.append(pred)
+                # Write (update value memory with response)
+                if t < seq_len - 1:
+                    resp_embed = responses[:, t].float().unsqueeze(-1).expand_as(r)
+                    combined = r * resp_embed
+                    erase = torch.sigmoid(self.erase_linear(combined))
+                    add = torch.tanh(self.add_linear(combined))
+                    value_mem = value_mem * (1 - w.unsqueeze(-1) * erase.unsqueeze(1)) + \
+                                w.unsqueeze(-1) * add.unsqueeze(1)
+
+            return torch.stack(predictions, dim=1).squeeze(-1)
+
+
+def load_model(path: str = _MODEL_PATH) -> bool:
+    """Load trained DKVMN weights. Returns True if successful."""
+    global _model, _model_loaded
+    if not _TORCH_AVAILABLE:
+        return False
+    if not os.path.exists(path):
+        return False
+    try:
+        _model = DKVMN()
+        _model.load_state_dict(torch.load(path, map_location="cpu"))
+        _model.eval()
+        _model_loaded = True
+        logger.info("DKVMN model loaded from %s", path)
+        return True
+    except Exception as exc:
+        logger.warning("Failed to load DKVMN model: %s", exc)
+        return False
+
+
+async def predict_mastery(pool, user_id: int) -> dict[str, float]:
+    """Return concept mastery scores {concept_id: 0.0-1.0}.
+
+    Uses DKVMN if trained model is available, otherwise falls back to DB.
+    """
+    # Fallback: read from concept_mastery or concept_elo tables
+    try:
+        rows = await pool.fetch(
+            "SELECT concept_id, mastery_score FROM concept_mastery WHERE user_id = ?",
+            user_id,
+        )
+        if rows:
+            return {r["concept_id"]: float(r["mastery_score"]) for r in rows}
+
+        # ELO fallback: normalize to 0-1
+        elo_rows = await pool.fetch(
+            "SELECT concept_id, elo_score FROM concept_elo WHERE user_id = ?",
+            user_id,
+        )
+        if elo_rows:
+            scores = [r["elo_score"] for r in elo_rows]
+            min_s, max_s = min(scores), max(scores)
+            rng = max_s - min_s or 1
+            return {
+                r["concept_id"]: round((r["elo_score"] - min_s) / rng, 3)
+                for r in elo_rows
+            }
+    except Exception as exc:
+        logger.debug("predict_mastery DB fallback failed: %s", exc)
+
+    return {}