🎓 HeySym - Hệ thống học SymPy với AI

Môi trường học tập trực tuyến tích hợp JupyterHub, nbgrader và AI trợ lý (Ollama) dành cho sinh viên học toán với SymPy.

🌐 Live Demo: https://HeySym.truyenthong.edu.vn

---

✨ Features

• 🎓 JupyterHub Multi-user - Hỗ trợ 15-20 người dùng đồng thời
• 📝 nbgrader Integration - Quản lý và chấm bài tự động
• 🤖 AI Assistant - Ollama với nhiều models (Kimi, GPT OSS, GLM, deepseek-r1)
• 🔐 Admin Approval - Bảo mật với phê duyệt người dùng thủ công
• 🌐 Cloudflare Tunnel - Truy cập an toàn qua HTTPS
• 📊 SymPy Focus - Tối ưu cho toán học ký hiệu Python
• 🎨 JupyterLab Interface - Giao diện hiện đại, dễ sử dụng

---

🚀 Quick Start

# 1. Clone repository
git clone https://github.com/phucdhh/HeySym.git
cd HeySym

# 2. Tạo môi trường Python
python3.11 -m venv venv
source venv/bin/activate

# 3. Cài đặt dependencies
pip install jupyterhub jupyterlab nbgrader jupyter-ai sympy \
  numpy scipy matplotlib pandas jupyterhub-nativeauthenticator

# 4. Tạo cấu hình
mkdir -p config courses logs exchange
cd config && jupyterhub --generate-config

# 5. Khởi động (local test)
jupyterhub -f config/jupyterhub_config.py

Truy cập: http://127.0.0.1:3333

---

🏗️ Kiến trúc Hệ thống

Internet → Cloudflare Tunnel → Mac Mini M2 (24GB RAM)
                                      ↓
                   ┌──────────────────┼──────────────────┐
                   ↓                  ↓                  ↓
            JupyterHub          Ollama (AI)        nbgrader
            (Port 3333)        (Port 11434)       (Port 3334)
                   ↓                  ↓                  ↓
           15-20 Users          4+ Models        Auto-grading

Stack công nghệ:

• Backend: JupyterHub + JupyterLab
• AI: Ollama (Kimi ⭐, GPT OSS, GLM, deepseek-r1:8b)
• Grading: nbgrader
• Auth: NativeAuthenticator (admin approval)
• Tunnel: Cloudflare (SSL/HTTPS)
• Math: SymPy, NumPy, SciPy, Matplotlib

---

📦 System Requirements

Production Server

• OS: macOS (headless) / Linux
• RAM: 24GB+ (hỗ trợ 15-20 concurrent users)
• Storage: 50GB+ SSD
• CPU: Apple M2 / Intel i5+ / AMD Ryzen 5+
• Network: Stable internet connection

Software

• Python 3.11+
• Node.js 16+ (cho configurable-http-proxy)
• Ollama
• cloudflared

---

🎯 Use Cases

Dành cho Sinh viên

• 📚 Học SymPy trong môi trường Jupyter interactive
• 🤖 Nhận hỗ trợ từ AI assistant bằng tiếng Việt
• 📝 Làm và nộp bài tập trực tuyến
• ✅ Nhận feedback tự động từ nbgrader

Dành cho Giảng viên

• 📋 Tạo và quản lý assignments với nbgrader
• 🔍 Chấm bài tự động với autograder
• 👥 Quản lý nhiều lớp học
• 📊 Theo dõi tiến độ sinh viên

Dành cho Admins

• 🔐 Phê duyệt người dùng mới
• 📈 Monitor system resources
• 💾 Backup & restore
• ⚙️ Cấu hình resource limits

---

🤖 AI Models

HeySym tích hợp Ollama với nhiều AI models:

Model	Type	Khả năng	RAM Local	Khuyến nghị
Kimi	Cloud	Tiếng Việt, reasoning	0GB	⭐ Production
GPT OSS	Cloud	General purpose	0GB	Alternative
GLM	Cloud	Multilingual	0GB	Alternative
deepseek-r1:8b	Local	Math, coding, offline	~8GB	Demo/Offline

💡 Khuyến nghị: Dùng Kimi (Cloud) làm default cho production → Không tốn RAM local, scale tốt, tiếng Việt native.

---

⚙️ Configuration Highlights

JupyterHub

• Port: 3333 (local), HTTPS via Cloudflare
• Auth: NativeAuthenticator + Admin approval
• Resource Limits: 3GB RAM, 2 CPU cores per user
• Idle Timeout: Configurable

AI (Ollama)

• Default Model: Kimi (Cloud)
• Host: http://localhost:11434
• Fallback: deepseek-r1:8b (Local)

nbgrader

• Exchange Directory: exchange/
• Timezone: Asia/Ho_Chi_Minh
• Auto-grading: Enabled

---

📊 Performance Metrics

Tested on Mac Mini M2 24GB RAM:

Metric	Value
Concurrent Users	15-20 (Cloud AI) / 6-8 (Local AI)
RAM Usage	~10-15GB (Cloud AI) / ~18-20GB (Local AI)
Response Time	<2s (notebook spawn)
Uptime	99%+ (with auto-restart)
Assignment Cycle	Create → Release → Submit → Grade (< 5 min)

---

🔒 Security Features

• ✅ HTTPS/SSL - Tự động qua Cloudflare Tunnel
• ✅ Admin Approval - Mọi user mới phải được admin phê duyệt
• ✅ Password Policy - Min 8 chars, check common passwords
• ✅ Resource Limits - Prevent resource abuse per user
• ✅ Isolated Environments - Mỗi user có notebook server riêng
• ✅ Private AI - Option to use local AI models (no data leaves server)

---

📖 Documentation

• PLAN.md - 📋 Kế hoạch triển khai chi tiết

  • Phase 1: Setup môi trường (1-2 ngày)
  • Phase 2: Testing & configuration (3-5 ngày)
  • Phase 3: Cloudflare Tunnel & Pilot (2-4 tuần)
  • Phase 4: Production & Scale (tuần 5+)
  • Troubleshooting guide
  • Success metrics & checklists

• User Guides (in PLAN.md)

  • Student guide - Đăng ký, làm bài, sử dụng AI
  • Teacher guide - Tạo bài tập, chấm bài
  • Admin guide - Approve users, monitor system

---

🛠️ Quick Troubleshooting

JupyterHub không khởi động

lsof -i :3333  # Check port conflict
tail -50 logs/jupyterhub.log  # Check logs

AI không phản hồi

curl http://localhost:11434/api/tags  # Check Ollama
brew services restart ollama  # Restart if needed

Assignment không fetch được

chmod -R 777 exchange/  # Fix permissions

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📝 License

Educational Use Only. See LICENSE file for details.

---

🙏 Acknowledgments

Built with amazing open-source projects:

• JupyterHub - Multi-user Jupyter server
• nbgrader - Assignment grading
• SymPy - Symbolic mathematics
• Ollama - Local AI models
• Cloudflare - Tunnel & SSL

---

📞 Contact & Support

• Author: Nguyễn Đăng Minh Phúc
• Email: ndmphuc@hueuni.edu.vn
• Phone: +84979555375
• Institution: Hue University of Education
• GitHub: @phucdhh

🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

---

📈 Project Status

Status: ✅ Ready for Production
Version: 1.0
Last Updated: February 2, 2026

---

Made with ❤️ for Education

⭐ Star this repo if you find it helpful!

📋 Deployment Plan · 🐛 Report Bug · 💡 Request Feature