Heng2004/Laos-Natural-Science-Chatbot

🐘 Laos Natural Science Chatbot (ວິທະຍາສາດ ທຳມະຊາດ ມ.1-ມ.4)

Chatbot ຕົວນີ້ອອກແບບສໍາລັບນັກຮຽນຊັ້ນ ມ.1-ມ.4 ໃນວິຊາວິທະຍາສາດທຳມະຊາດພາສາລາວ ໃຊ້ SeaLLM + JSONL ຂໍ້ມູນຈາກຕໍາລາປະຫວັດສາດ ແລະ Q&A ທີ່ຄູເພີ່ມເອງ (Teacher Panel) ພັດທະນາດ້ວຍ Gradio ແລະເຮັດວຽກໃນ Hugging Face Spaces.

✨ Features

• —👩‍🎓 Student Chat
• —ນັກຮຽນຖາມຄໍາຖາມວິທະຍາສາດທຳມະຊາດເປັນພາສາລາວ
• —ຄໍາຕອບສັ້ນໆ 2–3 ປະໂຫຍກ ເຂົ້າໃຈງ່າຍ ເໝາະກັບນັກຮຽນ ມ.1-ມ.4
• —ອີງຈາກຂໍ້ມູນໃນ JSONL ຕໍາລາ + Q&A ທີ່ຄູຕັ້ງໄວ້

• —👩‍🏫 Teacher Panel
• —ເພີ່ມ / ແກ້ໄຂ / ລຶບ Q&A ມື (บັນທຶກໃນ data/manual_qa.jsonl)
• —ຄໍາຕອບໃໝ່ຖືກນໍາໃຊ້ທັນທີໃນ Student Chat
• —ເບິ່ງຕາຕະລາງ Q&A ທັງໝົດ ແລະເລືອກແຖວເພື່ອແກ້ໄຂ

• —🧠 RAG + Embeddings
• —ດຶງຂໍ້ມູນຈາກ JSONL ຕໍາລາດ້ວຍ sentence-transformers (embedding-based retrieval)
• —ເລືອກຊິ້ນຂໍ້ມູນ (entries) ທີ່ໃກ້ຄຽງກັບຄໍາຖາມທີ່ສຸດ
• —ໃຊ້ SeaLLM ຕອບຄໍາຖາມໂດຍອີງຈາກ context ເຫຼົ່ານີ້

📁 Project structure

laos-history-chatbot/
├── app.py                 # Gradio UI (Student Chat + Teacher Panel)
├── model_utils.py         # SeaLLM, RAG, embeddings, chatbot logic
├── loader.py              # Load textbook JSONL + manual_qa.jsonl
├── qa_store.py            # In-memory storage & normalize_question
├── teacher_panel.py       # Teacher Panel actions (save/update/delete/select)
├── data/
│   ├── 1_Year_U_1.jsonl   # Curriculum (textbook) data
        ... (Still have more jsonl that I have to add)
│   └── manual_qa.jsonl    # Manual Q&A from teachers
├── requirements.txt       # Python dependencies
└── README.md              # This file

Local Hugging Face token setup (required for dataset sync)

Use one of these environment variables locally:

• —HF_TOKEN (recommended)
• —HUGGINGFACEHUB_API_TOKEN (fallback, also supported by this project)

PowerShell example:

$env:HF_TOKEN="hf_xxx_your_token"
python app.py

Tip: keep tokens only in environment variables, never hardcode them in source files.

Student and admin panels

The app has two separate panels:

• —APP_PANEL=student (default): public student chatbot only. No admin login, teacher panel, approval table, or admin callbacks are created in the UI.
• —APP_PANEL=admin: protected teacher/admin portal for Q&A submissions, Super Admin approval, and cache rebuilds.

Local student app:

python app.py

Local admin portal:

$env:APP_PANEL="admin"
python app.py

For deployment, run the public student app and admin portal as separate app/Space instances. Keep APP_PANEL=student for students and APP_PANEL=admin only for trusted staff.

Reloading approved Q&A

• —Teacher/Admin: click ໂຫຼດ Q&A ລ່າສຸດ to reread the shared local Q&A files and redraw the current unit table.
• —Student: click ໂຫຼດ Q&A ລ່າສຸດ to synchronize approved Q&A from the configured Hugging Face Dataset, rebuild the runtime lookup indexes, and refresh the selected unit's question list.
• —A reload button is an on-demand update, not automatic real-time push. It updates the process handling that click; the next semantic search lazily rebuilds Q&A embeddings from the refreshed questions.

If Student and Admin run in separate Spaces, both must use the same HF_DATASET_REPO_ID (or the project default), and Super Admin uploads must succeed for Student to receive the changes.

Role-based account setup

The Student panel is public. Teacher/Admin and Super Admin tools exist only in the Admin panel and require login.

Roles:

• —student: public chat only.
• —teacher: can submit Q&A add/update/delete/reorder requests for approval.
• —super_admin: can approve/reject teacher requests, apply live Q&A changes, and rebuild/upload cache.

For local development, open the Teacher page and log in once with:

• —teacher username: teacher
• —super admin username: superadmin

If a role has no password yet, the first login password is saved as a PBKDF2 hash in .auth_users.json. To reset local role accounts, delete .auth_users.json and start again. Existing .teacher_auth.json teacher passwords still work as a migration fallback.

For Hugging Face Spaces or server deployments, use environment secrets instead of local setup:

$env:APP_PANEL="admin"
$env:TEACHER_USERNAME="teacher"
$env:TEACHER_PASSWORD="your_strong_teacher_password"
$env:SUPER_ADMIN_USERNAME="superadmin"
$env:SUPER_ADMIN_PASSWORD="your_strong_super_admin_password"
python app.py

Command Prompt or Anaconda Prompt:

set APP_PANEL=admin
set TEACHER_USERNAME=teacher
set TEACHER_PASSWORD=your_strong_teacher_password
set SUPER_ADMIN_USERNAME=superadmin
set SUPER_ADMIN_PASSWORD=your_strong_super_admin_password
python app.py

For Hugging Face Spaces, add TEACHER_PASSWORD and SUPER_ADMIN_PASSWORD as Space secrets. Usernames are optional and default to teacher and superadmin.

Evaluation

Evaluation is documented in evaluation/README.md. The project reports the stored-question check only as the Exact-Match Manual Q&A Retrieval Test (a regression/data-integrity test), separately from unseen-question retrieval, human-scored answer quality, and hallucination/refusal results.

The supplied evaluation/test_questions.jsonl contains five is_example=true placeholders, not research data. Teachers should replace them with a reviewed 20–30-question pilot, manually verify the source IDs, and freeze the dataset before running generation. The lightweight validate command checks JSONL schema; the authoritative source-catalog check occurs at the start of run:

python scripts/evaluate_manual_qa_retrieval.py
python evaluate_chatbot.py validate --questions evaluation/test_questions.jsonl --config evaluation/evaluation_config.json
python evaluate_chatbot.py freeze --questions evaluation/test_questions.jsonl --config evaluation/evaluation_config.json
python evaluate_chatbot.py run --questions evaluation/test_questions.jsonl --config evaluation/evaluation_config.json --details evaluation/results_detailed.csv --scores evaluation/human_scores.csv --summary evaluation/results_summary.json
python evaluate_chatbot.py summarize --details evaluation/results_detailed.csv --scores evaluation/human_scores.csv --summary evaluation/results_summary.json --config evaluation/evaluation_config.json

The primary evaluation uses pipeline_scope=deployed_chatbot and calls the real Manual Q&A → glossary → textbook Top-4/SeaLLMs router. It records the selected answer route and direct-source provenance. Top-4 contexts are marked as generation inputs only when the answer actually reaches RAG; for direct Q&A/glossary answers they are a separate textbook-retrieval diagnostic. SeaLLMs hallucination results and the broader all-route unsupported-information result are reported with separate denominators. Do not report pilot placeholders, unresolved reviews, incomplete human scores, or uncomputed percentages as final research findings.