latest

2025-07-14 10:14:20 +04:00
parent 890acbd5bc
commit 868c9b252c
21 changed files with 615 additions and 97 deletions
@@ -0,0 +1,99 @@
+# 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**