--- license: apache-2.0 --- # TensorTalk / UM_Handbook TensorTalk is a handbook-grounded academic chat assistant built for the **Faculty of Computer Science and Information Technology, Universiti Malaya (UM)**. This project focuses on turning UM handbook content into a usable question-answering system through: - handbook preprocessing - source chunk construction - supervised QA dataset building - Qwen3-8B LoRA fine-tuning - merged-model deployment - a browser-style HTML chat demo --- ## Project Goal The main goal of this project is to build a handbook-based assistant that can answer student questions using information learned from the UM handbook domain. The current version is designed around: - undergraduate and postgraduate handbook content - handbook-faithful answers - concise student-facing responses - a local/demo deployment workflow on DICC and notebook environments This project is also intended to support a broader experimental pipeline: - **Baseline 1:** closed-book supervised fine-tuning - **Baseline 2:** retrieval-augmented version for later comparison --- ## What This Project Contains ### 1. Dataset Preparation The project includes scripts and resources for preparing handbook data before fine-tuning: - handbook markdown preprocessing - source chunk dataset building - SFT QA dataset construction - configuration management for the preprocessing and dataset pipeline ### 2. Fine-Tuning Workflow The model training workflow uses a Qwen3-8B base model with LoRA-based fine-tuning on the UM handbook QA dataset. The fine-tuning workflow includes: - notebook-based training on DICC - device-aware loading logic - train / validation / test style evaluation workflow - merged-model export for direct inference - LoRA adapter export for optional PEFT-based reuse - metrics and prediction file generation ### 3. Deployment Demo The project includes a notebook-based HTML chat UI called **TensorTalk**. The demo provides: - a browser-style chat layout - a handbook-focused system prompt - merged-model loading for direct inference - a student-facing question-answer workflow - a simple deployment path for demonstration purposes --- ## Current Project Structure ```text UM_Handbook/ ├── Dataset/ │ └── SFT_Dataset/ │ ├── SFT_QA_Training_Ready.jsonl │ ├── SFT_QA_Training_Ready_pretty.json │ ├── SFT_QA_Metadata.jsonl │ └── SFT_QA_Metadata_pretty.json ├── assets/ ├── outputs/ │ └── qwen3_um_handbook_optimized_1/ │ ├── lora_adapter/ │ ├── merged_model/ │ ├── trainer_runs/ │ ├── test_eval_runs/ │ ├── dataset_split_summary.json │ ├── final_metrics.json │ ├── test_predictions.jsonl │ └── validation_predictions.jsonl ├── FineTune_QWEN3_UM_Handbook_optimized_1.ipynb ├── UM_Handbook_Markdown_Preprocess.py ├── UM_SFT_QA_Dataset_Builder_from_Index.py ├── UM_Source_Chunk_Dataset_Builder.py └── um_handbook_config.py ``` --- ## Key Files ### Training and Data - `Dataset/SFT_Dataset/SFT_QA_Training_Ready.jsonl` Main SFT training dataset used for handbook QA fine-tuning. - `UM_Handbook_Markdown_Preprocess.py` Preprocesses handbook markdown / extracted source text. - `UM_Source_Chunk_Dataset_Builder.py` Builds source chunks for downstream dataset and retrieval-related use. - `UM_SFT_QA_Dataset_Builder_from_Index.py` Builds the supervised QA dataset from curated handbook content. - `um_handbook_config.py` Central configuration file for paths and data-processing settings. ### Training Output - `outputs/qwen3_um_handbook_optimized_1/merged_model/` Main inference-ready model directory. This is the directory used by the demo chat UI. - `outputs/qwen3_um_handbook_optimized_1/lora_adapter/` LoRA adapter weights. This is useful for PEFT-style loading with a base model, but it is not the primary path used by the current demo UI. - `outputs/qwen3_um_handbook_optimized_1/final_metrics.json` Final evaluation summary. - `outputs/qwen3_um_handbook_optimized_1/validation_predictions.jsonl` Validation-set generated answers for inspection. - `outputs/qwen3_um_handbook_optimized_1/test_predictions.jsonl` Test-set generated answers for inspection. ### Demo - `FineTune_QWEN3_UM_Handbook_optimized_1.ipynb` Main notebook that contains the fine-tuning workflow and the TensorTalk HTML chat demo. --- ## Model Artifact Notes This project may contain several model-related outputs. They are not all used in the same way. ### `merged_model/` This is the most important deployment artifact for the current demo. Use this when: - running the current TensorTalk HTML chat UI - loading the fine-tuned model directly with Hugging Face `from_pretrained(...)` - sharing the main inference-ready model ### `lora_adapter/` This contains LoRA delta weights only. Use this when: - loading the adapter on top of the original base model - reusing the fine-tuning result in a PEFT workflow - experimenting with a smaller transferable fine-tuning artifact ### `.pt` exported model file If present, the `.pt` file is mainly a saved full-model artifact / backup export. Use this when: - archiving the full fine-tuned weights - running a custom loading workflow that explicitly expects a `.pt` file For the current TensorTalk chat UI, the primary runtime artifact is still **`merged_model/`**. --- ## Current Demo Behavior The current demo is designed to answer questions such as: - dress code and appearance guidance - programme core courses / credit requirements - undergraduate vs postgraduate handbook information - academic rules and handbook-supported policy questions The answer style is intended to be: - handbook-grounded - short and direct - student-facing - non-speculative --- ## Example Demo Output The screenshot below shows the current TensorTalk chat interface running with the fine-tuned UM handbook model. ![TensorTalk Demo](assets/tensortalk_demo_chat.jpg) --- ## Repository Preview The screenshot below shows the current top-level project layout. ![Repository Structure](UM_Handbook/assets/tensortalk_demo_chat.jpg) --- ## Suggested Minimal Deployment Package If the goal is only to demonstrate the chat UI to teammates, the minimal useful set is: - `merged_model/` - the chat notebook / UI code - optional avatar image under `assets/` The following items are not required for a simple demo run: - intermediate training checkpoints - test evaluation run directories - optional full `.pt` export - raw training logs not used by the demo --- ## Notes - The project is organized so that **Dataset**, **models / outputs**, and **demo code** remain separate. - The current demo is notebook-friendly and was prepared around a DICC workflow. - The deployment path prioritizes clarity and reproducibility over a heavyweight full-stack application setup. --- ## Status Current project status: - handbook preprocessing pipeline prepared - supervised QA dataset prepared - LoRA fine-tuning workflow completed - merged model exported - TensorTalk HTML chat demo running - evaluation outputs generated --- ## Author / Project Name **TensorTalk** UM Handbook QA / Fine-Tuned Qwen3-8B LoRA Project