4. Requirements4.10 Chat agents
Chat Agents — OpenRouter & Personas
One OpenRouter gateway, multimodal models, and a customisable chat agent per user — Student, Educator, Company, and Admin packs.
Decision (locked for product design)
| Choice | Value |
|---|---|
| LLM gateway | OpenRouter — single API key, multi-provider, model hot-swap |
| Multimodal | Yes — text + images + PDFs (certificates, attendance sheets, NRIC/passport scans where allowed) |
| Agent model | Every user gets their own chat agent (isolated threads + memory scoped to that user) |
| Customisation | Persona packs + per-org overrides (prompt, tools, model tier, knowledge scope) |
| Phase | Phase 2 after Plan SOQ-25K core TMS go-live (not in the 28-day MVP build) |
Why OpenRouter
- One integration — SOQ TMS talks to OpenRouter only; swap models without rewriting the app.
- Open + closed models — use open-weight for cost, premium closed for hard funding/policy questions.
- Failover — if one provider is down, route to a backup model ID.
- Spend control — per-model and per-org budgets; log every call with
user_id+agent_id.
Secrets: OpenRouter API key lives in server env only. Browsers never see the key. Chat goes through SOQ TMS /api/chat with auth + RBAC.
Recommended models (via OpenRouter)
Pick one default + one open + one premium. Admin can change the mapping later without a deploy.
| Tier | Suggested OpenRouter model | Use for | Multimodal |
|---|---|---|---|
| Default (volume) | google/gemini-2.5-flash (or current Gemini Flash on OpenRouter) | Student & educator everyday chat, image/PDF Q&A | Text - image - PDF |
| Open-weight | qwen/qwen2.5-vl-72b-instruct (or current Qwen VL / Qwen3 VL Max) | Cost control, open-model preference, on-prem path later | Text - image |
| Premium reasoning | anthropic/claude-sonnet-4 (or current Claude Sonnet) | Admin / funding / policy answers that need careful grounding | Text - image |
| Budget fallback | openai/gpt-4o-mini or Gemini Flash-Lite | Outage failover, short FAQ replies | Text - image |
Practical default for SOQ
| Choice | Model | Why |
|---|---|---|
| Default | Gemini Flash | Best speed / cost / multimodal for training ops |
| Open option | Qwen VL | Org-wide or per-persona open-weight preference |
| Premium (Admin / funding) | Claude Sonnet | Closer adherence to policy text |
Model IDs on OpenRouter change over time. Store them as config (
agent_profiles.model_id), not hard-coded constants. Re-validate IDs at kickoff of Phase 2.
Persona packs (customisable)
Every signed-in user gets their own agent instance: private thread history, optional short-term memory, and tools limited by role.
| Persona | Who | Agent job | Allowed context (RAG / tools) | Default model tier |
|---|---|---|---|---|
| Student | Learners | Course help, schedule, fees due, attendance status, "what's next" | Own enrolment, timetable, invoices, course materials | Default (Flash) |
| Educator | Trainers / lecturers | Roster, session prep, attendance help, marking guidance | Own classes, roster, session materials | Default (Flash) |
| Company | Corporate sponsors / HR | Staff enrolments, invoices, progress summaries | Own company cohort only | Default (Flash) |
| Admin | SOQ ops / admissions / finance | Ops Q&A, Student 360 summaries, SWDA status explainers | Role-scoped TMS data + approved SOP docs | Premium (Sonnet) |
| Sales (optional) | Agents / CRM users | Lead follow-up scripts, course recommenders | Own leads + public catalogue | Default (Flash) |
What “customisable” means
SOQ (or AIEE.DEV on behalf of SOQ) can edit without code:
| Setting | Example |
|---|---|
| Display name & avatar | "SOQ Study Buddy", "Trainer Copilot" |
| System prompt | Tone, language (EN first; ZH later), what to refuse |
| Model tier | Default / Open / Premium |
| Knowledge bases | Course handbook, FAQ, SOPs (per persona) |
| Tools on/off | Lookup attendance - create lead note - draft email (never auto-submit SWDA) |
| Modalities | Text only - text+image - text+image+PDF |
| Guardrails | No PII to other students; no inventing grant amounts; escalate to human |
Product behaviour
Rules (non-negotiable)
- One agent per user — no shared chat history across students.
- RBAC before RAG — the agent only sees what the user’s role already allows in the TMS.
- No silent government submits — SWDA / Xero writes need human confirmation.
- PDPA — chat logs retention policy; redact NRIC in prompts where possible; Singapore region storage preference.
- Audit — every reply stores
model_id, tokens, persona, and whether tools were used.
Scope vs Plan SOQ-25K
| In Plan SOQ-25K (28 days) | Phase 2 Chat Agents |
|---|---|
| Core TMS portals, SWDA hub skeleton, Xero path | OpenRouter gateway + chat UI |
| Rules engine / workflow automation | Persona packs + per-user agents |
| Document storage | Multimodal upload in chat |
| — | Admin console to customise agents |
Commercial: Phase 2 is a fixed add-on — quote separately after core handoff (no maintenance retainer).
Acceptance criteria (Phase 2)
- OpenRouter key configured; chat works for Student and Admin personas in staging.
- Multimodal: user uploads a PDF or image and gets a grounded answer from allowed context.
- Student A cannot see Student B’s chat or enrolment data via the agent.
- Admin can change model tier and system prompt for the Student pack without a deploy.
- Failover: if primary model errors, agent retries with configured fallback model.
Related
| Link |
|---|
| 4.9 Platform services — RBAC, notifications, audit |
| 4.11 Ops modules — Singpass - payments - CareerFuture add-ons |
| 4.12 Business benefits — Phase 2 capability map |
| 4.7 Student & trainer — portal surfaces where chat lives |