100 lines
3.7 KiB
Markdown
100 lines
3.7 KiB
Markdown
# UTAS University Portal Chatbot System Documentation
|
|
|
|
## Overview
|
|
The UTAS University Portal Chatbot ("University Assistant") is a multilingual AI-powered assistant designed to:
|
|
|
|
- Provide general university information to anonymous (logged-out) visitors.
|
|
- Offer personalized guidance based on user authentication and role when logged in.
|
|
- Support both English and Arabic using a hybrid rule-based knowledge search and LLM fallback.
|
|
- Integrate with OpenRouter (OpenAI-compatible) and/or Ollama local models (e.g., `command-r7b-arabic`).
|
|
|
|
## Architecture
|
|
```
|
|
Frontend (ChatWidget.tsx)
|
|
↕
|
|
API Route (`/api/chat/route.ts`)
|
|
↕
|
|
Backend Bot Engine (`src/lib/chatbot.ts`)
|
|
↔
|
|
Knowledge Base (`src/lib/utasKnowledgeBase.ts`)
|
|
↔
|
|
User Context (AuthProvider)
|
|
↕
|
|
AI Provider (OpenRouter SDK / Ollama client)
|
|
```
|
|
|
|
### Frontend
|
|
|
|
- **`ChatWidget`**: React component, toggles between general and mental-health modes.
|
|
- Surveys and escalation logic are built-in.
|
|
- Uses **fetch** to POST messages to `/api/chat`.
|
|
- **User Context Integration**: Automatically includes user role and profile data from AuthProvider when user is logged in.
|
|
|
|
### API Layer (`/api/chat`)
|
|
|
|
- **`POST /api/chat`**: Accepts `{ message, mode?, history?, userContext? }`, initializes `UTASChatBot` with API key from `.env.local`.
|
|
- **`GET /api/chat`**: Returns service status and supported features.
|
|
|
|
### Bot Engine (`UTASChatBot`)
|
|
|
|
- **Language Detection**: Simple regex-based Arabic detection.
|
|
- **Rule-based KB Search**: Returns up to 3 relevant items from structured knowledge base.
|
|
- **LLM Fallback**: Configurable system prompts for OpenAI or Ollama.
|
|
- **Personalized Responses**: Adjusts responses based on user role and profile data.
|
|
- **Ollama Integration**: Falls back to local Ollama model if no OpenRouter API key.
|
|
|
|
## Authentication & Personalization
|
|
|
|
1. **Anonymous (Logged-out)**: Returns only publicly available course, admission, scholarship info. No user-specific data.
|
|
2. **Authenticated**: When user is logged in, passes user `role` and `profile` as part of request payload. Bot tailors responses (e.g., shows application status, next steps).
|
|
|
|
### Personalization Implementation
|
|
|
|
- Frontend includes `user.role` and profile data from AuthProvider in `/api/chat` request.
|
|
- `UTASChatBot.generateResponse` accepts `userContext` parameter.
|
|
- System prompts are dynamically generated based on user role and context.
|
|
- Different handling for students, faculty, staff, and admin roles.
|
|
|
|
## AI Provider Integration
|
|
|
|
- **OpenRouter**: Default via `process.env.OPENROUTER_API_KEY`.
|
|
- **Ollama**: Uses local model specified by `MODEL_COMMAND_R7B` if OpenRouter key is not available.
|
|
|
|
### Configuration
|
|
|
|
Create a `.env.local` at project root:
|
|
|
|
```env
|
|
OPENROUTER_API_KEY=sk-... (your credits)
|
|
OLLAMA_URL=http://localhost:11434
|
|
MODEL_COMMAND_R7B=command-r7b-arabic
|
|
```
|
|
|
|
## Layout & UI Fixes
|
|
|
|
- Landing-page container elements updated with `max-w-7xl`, `overflow-x-hidden`, and responsive padding.
|
|
- Consistent margins maintained when switching between slides or tabs.
|
|
|
|
## Testing
|
|
|
|
- Integration tests verify different response behaviors:
|
|
- Anonymous chat returns only public information
|
|
- Authenticated chat returns personalized responses based on user role
|
|
- Language switching (English/Arabic) works in all modes
|
|
- Ollama fallback activates when OpenRouter key is not available
|
|
|
|
## Progress Tracker
|
|
|
|
- [x] Create system-level docs (this file)
|
|
- [x] Expose user context in frontend requests
|
|
- [x] Extend API route to accept user context
|
|
- [x] Update `UTASChatBot` for role-based prompts
|
|
- [x] Integrate Ollama client as alternative provider
|
|
- [x] Write tests for both anonymous and authenticated flows
|
|
- [x] Fix landing-page layout `out-of-margin` issues
|
|
- [ ] QA and deploy
|
|
|
|
---
|
|
|
|
**Updated on July 13, 2025**
|