ReframeBot is a CBT-oriented chatbot for supporting university students with academic stress. It combines a fine-tuned Llama 3.1 model with a guardrail router (TASK_1/TASK_2/TASK_3) and optional RAG grounding from a CBT knowledge base.
Our trained models are available on Hugging Face:
- SFT Adapter - Supervised Fine-Tuning adapter for Llama 3.1 8B
- DPO Adapter - Direct Preference Optimization adapter
- Guardrail Classifier - Task classifier for message routing (CBT/Crisis/Out-of-scope)
- Fine-tuned Llama 3.1 8B (DPO adapter)
- Guardrail routing with crisis detection and out-of-scope redirection
- Optional RAG grounding over a CBT knowledge base
- FastAPI backend and a lightweight static web UI
- Python 3.11+
- CUDA-capable GPU (recommended)
- 16GB+ RAM
- Clone the repository:
git clone https://github.com/minhnghiem32131024429/ReframeBot.git
cd ReframeBot- Install dependencies:
pip install -r requirements.txt-
Download models from Hugging Face:
- SFT Adapter: ReframeBot-SFT-Llama3.1-8B
- DPO Adapter: ReframeBot-DPO-Llama3.1-8B
- Guardrail Model: ReframeBot-Guardrail-DistilBERT
-
Create a local config file (recommended):
- Copy
.env.exampleto.env - Update paths as needed (example):
- Copy
GUARDRAIL_PATH=D:\\Work\\AI\\guardrail_model_retrained\\best
GUARDRAIL_CONTEXT_TURNS=3Notes:
.envis ignored by git by design.- Model checkpoints are not committed to this repo; point
GUARDRAIL_PATHto your local folder.
- Run the FastAPI server:
python app.py- Serve the web UI (in a new terminal):
cd web
python -m http.server 8080- Open: http://localhost:8080/
The UI will call the backend at http://127.0.0.1:8000/chat.
ReframeBot/
├── app.py # FastAPI backend with guardrail integration
├── train.ipynb # Training notebook (SFT + DPO + Guardrail)
├── web/
│ ├── index.html # Main HTML file
│ ├── style.css # Glassmorphism styles
│ └── script.js # Frontend logic
├── data/
│ ├── dataset.jsonl # SFT training data
│ ├── dataset_dpo.jsonl # DPO training data
│ └── guardrail_dataset.jsonl # Guardrail training data
├── scripts/
│ ├── check_data.py # Dataset validation
│ ├── check_dpo_dataset.py
│ ├── push_to_hub.py # Upload single model
│ └── push_all_models.py # Upload all models
├── docs/
│ └── SETUP.md # Detailed setup guide
├── Utils/ # Background assets
├── requirements.txt # Python dependencies
└── README.md
- Glassmorphism-style layout (HTML/CSS)
- Responsive chat UI
Edit web/script.js:
const API_URL = "http://your-domain.com/chat";You can override routing behavior without editing code via .env:
GUARDRAIL_PATH: local folder path to a transformers text-classification checkpointGUARDRAIL_CONTEXT_TURNS: number of recent user turns concatenated for guardrail input (default: 3)GUARDRAIL_CONTEXT_MAX_CHARS: max characters used for guardrail input (default: 700)CRISIS_SEMANTIC_SIM_THRESHOLD,CRISIS_SEMANTIC_SIM_MARGIN: semantic crisis detector thresholdsROUTER_EMBED_MODEL: embedding model used for routing/RAG (default:all-MiniLM-L6-v2)
Edit web/style.css to change color scheme, glass effects, and more.
See train.ipynb for the complete training pipeline:
- SFT (Supervised Fine-Tuning) - Base model adaptation
- DPO (Direct Preference Optimization) - Response quality improvement
- Guardrail Training - Task classification model
Optional scripts:
scripts/prepare_guardrail_data.py: merge + deduplicate guardrail data (and add hard negatives)scripts/train_guardrail.py: retrain the guardrail classifier from a JSONL dataset
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Nghiem Nhat Minh
- GitHub: @minhnghiem32131024429
- Hugging Face: @Nhatminh1234
- Meta AI for Llama 3.1
- Hugging Face for transformers and PEFT libraries
- FastAPI team