Đầu ra có cấu trúc và kiểm định

1. Mục tiêu

Output có cấu trúc ngăn mô hình hoặc client tạo field sai kiểu, thiếu trường bắt buộc hoặc làm sai semantics của Knowledge State.

Pipeline bắt buộc cho mọi output LLM:

schema-constrained generation
→ validation
→ retry
→ repair
→ validation lần nữa
→ deterministic fallback

Không dùng json.loads() trần như lớp bảo vệ duy nhất.

2. Contract validation hiện hành

Các Pydantic model chính đặt extra="forbid". Hệ quả:

• client gửi thêm score, mastery hoặc evidence_confidence trong answer payload bị từ chối;
• câu hỏi trả cho client không chứa expected_answer hoặc rubric;
• not_assessed/unverified không được mang mastery;
• partial/verified phải có mastery, confidence và evidence IDs;
• question_bank_version phải có khi kết luận dựa trên evidence;
• generated_disclaimer không được rỗng.

3. Server-authoritative fields — trường do server làm chủ

Client không được quyết định:

question order
expected answer
rubric
score
misconception severity
mastery
evidence confidence
diagnostic status
Need / Importance / Urgency
Priority score / rank
Capacity ratio / status

4. LLM usage — ba đường đang bật

Mọi đường đều dùng chung một LLM factory: get_llm() (src/services/llm.py) gọi NVIDIA NIM API với temperature=0.0 và model đọc động từ NVIDIA_LLM_MODEL (ví dụ nemotron-3-nano-30b-a3b, nemotron-3-super-120b-a12b). Key LLM và key embedding là hai biến môi trường riêng, không fallback cho nhau.

Trình tự parse hiện hành, đúng theo thứ tự trong src/services/llm.py:

raise_if_truncated        # response bị cắt ≠ response rác
→ parse_json_response     # chịu được ```json fence và text bao quanh
→ cắt từ "{" đầu tới "}" cuối
→ escape_stray_backslashes  # repair CÚ PHÁP, chỉ sau khi parse chặt vỡ
→ Pydantic model validate
→ guardrail validator: nhận hoặc TỪ CHỐI
→ bị từ chối → baseline tất định nguyên khối

escape_stray_backslashes chỉ nhân đôi các \ không mở đầu một escape JSON hợp lệ — ký hiệu toán kiểu LaTeX (\Theta, \log) trong nội dung tiếng Việt từng làm cả một đề xuất đúng bị đọc thành rác. Nó không phải repair ở tầng guardrail: không chữ nào trong đề xuất bị sửa nghĩa. Hybrid §2 luật 1 vẫn nguyên — validator từ chối, không bao giờ viết lại.

parse_json_response thất bại tường minh bằng ValueError, không trả dict rỗng: nuốt lỗi ở đây sẽ thành điểm 0 oan cho người học.

5. Fail closed và fallback

• Fail closed — đóng khi lỗi: thiếu tín hiệu ưu tiên thì không rank.
• Fallback — phương án dự phòng: Study Workspace có thể dùng nội dung tối thiểu hoặc dataset frontend.
• No fabrication — không bịa dữ liệu: không thay mastery/deadline/importance thiếu bằng 0.

6. Determinism — tính tất định

Agent 2 MCQ, toàn bộ phần chấm điểm của Agent 3 và toàn bộ allocator của Agent 4 không dùng randomness hoặc LLM. Bất biến bao trùm: đặt ai_enrichment_enabled = false thì hệ thống vẫn hoạt động đầy đủ và cho kết quả giống từng byte với baseline — kill switch không phải chế độ suy giảm.

Để tái tạo kết quả, request Agent 3 nên truyền evaluated_at; nếu bỏ trống, server dùng thời gian hiện tại, làm urgency thay đổi giữa hai lần gọi. Lượt gọi thứ hai lấy advisory phải dùng lại đúng evaluated_at của lượt đầu, nếu không narrative sẽ mô tả một Priority Set khác. Agent 4 không đọc đồng hồ server: mốc duy nhất là plan_start_date trong request.

7. Disclaimer

Hai contract chẩn đoán và ưu tiên đều phải mang generated_disclaimer. Disclaimer không biến kết quả sai thành đúng; nó làm rõ đây là khuyến nghị hỗ trợ học tập, không phải đánh giá hay lịch chính thức của giảng viên.

8. Thuật ngữ

• Schema-constrained — bị ràng buộc bởi schema: output chỉ được có hình dạng đã định nghĩa.
• Validation — kiểm định: kiểm tra kiểu, miền giá trị và bất biến nghiệp vụ.
• Retry — thử lại: gọi lại khi output sai.
• Repair — sửa cấu trúc: đưa output về schema rồi validate lại.
• Fallback — dự phòng: kết quả an toàn khi luồng chính thất bại.
• Server-authoritative — server có thẩm quyền: client không thể ghi đè.

9. Tham chiếu code

• src/agents/schemas/knowledge_state.py
• src/agents/schemas/diagnostic_io.py
• src/agents/schemas/learning_priority.py
• src/agents/nodes/study_generator.py
• src/agents/diagnostic/guardrails.py
• src/agents/priority/advisory_guardrails.py
• src/services/llm.py