HNUE AI Academic Advisor — V1

Web app local bằng FastAPI và React với một giao diện chính: chat cùng cố vấn AI và bảng điểm ở cạnh bên. Dán trực tiếp bảng TSV sao chép từ trang trường; Python giữ cả dòng chưa có điểm và điểm 0, rồi hiển thị mã môn, tên môn, tín chỉ, điểm hệ 10, hệ 4 và điểm chữ.

Các phép tính học vụ và thay đổi dữ liệu nằm trong Python tool. Gemini chỉ chọn tool và diễn giải kết quả theo schema AdvisorResponse. Hành động ghi dữ liệu luôn dừng ở một nút xác nhận cho đúng tham số đã chuẩn bị phía server. Inspector LOCAL DEBUG cho thấy catalog và tool call thật; đây không phải vai trò quản trị hay ranh giới bảo mật.

Phạm vi tin cậy: dữ liệu HNUE đi kèm là dữ liệu một phần do người dùng cung cấp, chưa đủ để xác nhận tốt nghiệp chính thức. Màn hình và API luôn giữ trạng thái UNKNOWN/NEEDS_REVIEW cho phần chưa xác minh. V1 là ứng dụng local một người dùng, chưa có authentication để public.

Chạy nhanh

Yêu cầu: Python 3.11+, Node.js 20+ và pnpm/npm.

cd outputs/hnue-ai-academic-advisor
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
alembic upgrade head
python -m app.data.seed_cli
uvicorn app.main:app --reload

Ở terminal khác:

cd outputs/hnue-ai-academic-advisor/frontend
pnpm install
pnpm dev

Mở http://localhost:5173, dán bảng điểm vào panel bên phải rồi đặt câu hỏi. OpenAPI ở http://localhost:8000/docs.

Lần đầu mở app không tự chèn hồ sơ demo. Có thể yêu cầu cố vấn nạp dữ liệu demo qua chat; đây là hành động ghi dữ liệu nên ứng dụng luôn yêu cầu xác nhận.

Nếu không muốn dùng migration khi thử nhanh, FastAPI tự tạo bảng còn thiếu lúc khởi động; migration vẫn là cách được khuyến nghị.

Related MCP server: ScarletPlan

Chạy một địa chỉ bằng Docker

Docker build React trước, chép frontend/dist vào image Python rồi để FastAPI phục vụ cả giao diện và API:

docker compose up --build

Sau khi build:

• Giao diện: http://localhost:8000/

• API: http://localhost:8000/api/...

• OpenAPI: http://localhost:8000/docs

Đặt API key Gemini trong .env trước khi build:

GOOGLE_API_KEY=<api-key-tu-google-ai-studio>
GEMINI_MODEL=gemini-3.6-flash

compose.yaml truyền key vào backend để gọi Gemini Developer API. Database SQLite được giữ trong volume advisor-data.

Dừng ứng dụng:

docker compose down

Dữ liệu mẫu và import

POST /api/seed tạo curriculum HNUE một phần, hồ sơ DEMO-001, transcript minh họa và career mapping có nhãn. Lệnh seed có tính idempotent.

• Mẫu CSV: app/data/transcript_template.csv

• Dữ liệu minh họa: app/data/demo_transcript.csv

Luồng import qua chat/tool: preview CSV → xem warning/lỗi từng dòng → xác nhận commit. Unique key (student, course, semester, attempt_number) ngăn import lặp. Điểm và điểm chữ mâu thuẫn được giữ nguyên và báo warning.

Gemini và tool calling

LLM chỉ nhìn thấy 8 tool nghiệp vụ: get_academic_status, lookup_academic_rules, check_graduation_progress, calculate_gpa_goal, simulate_grades, recommend_grade_improvements, recommend_study_plan và explore_careers. Mỗi tool có Pydantic input/output schema; catalog và inspector hiển thị cả hai schema. Ví dụ, mục tiêu GPA số dùng {"target":{"type":"GPA","gpa":3.2}}, còn yêu cầu "bằng Khá" dùng {"target":{"type":"CLASSIFICATION","classification":"KHA"}}. Nếu chưa có ngưỡng xếp loại đã xác minh, tool trả UNKNOWN thay vì tự gán một GPA.

Cài phần AI:

pip install -r requirements-ai.txt

Sửa .env:

GOOGLE_API_KEY=<api-key-tu-google-ai-studio>
GEMINI_MODEL=gemini-3.6-flash

Vòng điều phối là Gemini → tool Python → Gemini, tối đa 6 lượt tool. Finalizer dùng function calling và bắt buộc tạo AdvisorResponse theo schema Pydantic. Nếu Gemini không phản hồi hoặc cấu hình thiếu, API trả AI_UNAVAILABLE thay vì tạo câu trả lời giả.

MCP

Cài requirements-ai.txt, seed database rồi chạy:

python -m app.mcp.server

Server FastMCP qua stdio expose:

get_student_profile, get_student_transcript, get_curriculum, check_graduation_requirements, check_requirement_groups, calculate_current_gpa, calculate_gpa_plan, recommend_retakes, match_career_to_specialization, recommend_courses, create_study_plan.

Kiểm tra discovery thật qua MultiServerMCPClient:

python -m app.mcp.client

Kiểm thử

pip install -r requirements-dev.txt
python -m pytest tests/test_advisor_tools.py tests/test_advisor_integration.py -q
pytest
cd frontend
pnpm install
pnpm build

Test bao phủ biên thang điểm, xung đột điểm, F rồi học lại đạt, các repeat policy, môn không tính GPA, GPA mục tiêu động/bất khả thi, requirement lồng nhau, retake exact search, credit limit động, API persistence, graceful degradation và MCP deterministic entry points.

API chính

• POST /api/profiles, GET /api/profiles

• GET /api/students/{id}/transcript, POST /api/students/{id}/attempts

• POST /api/students/{id}/import/preview, POST /api/students/{id}/import/commit

• GET /api/students/{id}/graduation, GET /api/students/{id}/gpa

• POST /api/gpa/plan, POST /api/retakes/plan

• GET /api/students/{id}/recommendations, GET /api/careers/match

• POST /api/scenarios, GET /api/scenarios

• POST /api/scenarios/{id}/recalculate

• GET /api/students/{id}/export, DELETE /api/students/{id}

• POST /api/advisor/sessions, GET /api/advisor/sessions/{id}

• POST /api/advisor/transcript/paste, POST /api/advisor/chat

• GET /api/advisor/tools, GET /api/advisor/sessions/{id}/traces

• POST /api/advisor/actions/confirm

Thiết kế và giới hạn

• Chính sách và câu hỏi chưa xác minh

• Kiến trúc

• Chưa có portal HNUE, OCR, email, lịch mở lớp và kiểm tra trùng giờ.

• Planner dùng backtracking hữu hạn để tìm packing theo tín chỉ và tự tăng số kỳ khi horizon không cố định; chưa xét lịch mở lớp nên không tuyên bố tối ưu lịch học thực tế.

• Các planning mode có objective riêng. CAREER_FOCUSED cần career mapping; GPA_FOCUSED cần target và expected_grade_points. Nếu thiếu, API trả UNSUPPORTED.

• Study scenario chỉ packing tập môn được chọn từ phần requirement còn thiếu. Output lưu contribution, alternatives và unknown groups; catalog elective không được đưa toàn bộ vào kế hoạch.

• GPA_FOCUSED trả required average, feasibility, projected GPA và nguồn dữ liệu (TRANSCRIPT_POLICY hoặc EXPLICIT_ASSUMPTION).

• Retake duyệt toàn bộ tổ hợp trong tối đa 20 candidate, tôn trọng hard cap kể cả môn bắt buộc và chỉ là exact trong tập candidate đã cho. Kết quả vẫn phụ thuộc policy/điểm giả định.

• Career mapping là biên tập tham khảo, không phải chuyên ngành chính thức. Curriculum tham chiếu trang FIT HNUE ngày 29/07/2023 nhưng cohort áp dụng và các mã xung đột vẫn để UNKNOWN.

• Session và bảng điểm dán chỉ ở bộ nhớ tiến trình. Scenario bấm lưu nằm trong database và mang provenance; kết quả từ snapshot cũ được đánh dấu stale khi đọc lại.

• Frontend package dùng latest để scaffold thuận tiện; với triển khai dài hạn nên commit lockfile sinh bởi pnpm install.