AI Assistant Integration

Status: plan, nothing implemented yet. Written on 04/11/2026 from the code of the four repos (LMS_Backend, LMS_Frontend and LMS_Documentation on chat+ai; LMS_ai_bot on before-integration). It supersedes LMS_Project/AI_ASSISTANT_INTEGRATION.md (14/10/2026); §13 lists what changed between the two.

1. The goal in one paragraph

A student who owns a training opens its course player (/student-my-content/student-training-details/:id), pulls out the right side panel and asks a question. The bot answers only from the Markdown files you uploaded for that training. You keep feeding the bot from its own React admin (http://localhost:5174/admin), but instead of typing a training id you pick the training from a dropdown filled from the Laravel catalog. The link between the two systems is set up once by the super admin: an application key so the bot can read Laravel’s catalog, and a signing secret so Laravel can issue short-lived student tokens the bot trusts. Every conversation is stored in the bot with the student’s identity, and every student has a daily quota.

2. Your mental model, checked

#	What you described	Verdict	What to adjust
1	The bot works on the student side, inside the training page’s right side panel.	✅ Correct	The panel already exists as a mockup (`TrainingAiAssistantWidget`, markers `TODO(ai)`). Only the wiring is missing.
2	From the super admin dashboard I generate an application key that replaces `dev-admin-key`.	⚠️ Two different keys	`dev-admin-key` is the bot’s own bootstrap admin key (`ADMIN_API_KEY`): it lets you call the bot’s admin API. The key the super admin generates is for the bot to call Laravel. Keep both ideas, but as two credentials: retire `dev-admin-key` in favour of the bot’s existing email + password login, and add the Laravel application key as a new “LMS connection” setting in the bot admin.
3	The bot gets limited access to a few Laravel endpoints, no security leak.	✅ Correct	Three read-only endpoints under `/api/ai-bot/*`, outside Sanctum, protected by the hashed application key, throttled, returning whitelisted fields only (no lesson content, no PII).
4	(not in your description) How does the student prove to the bot who they are and that they own the training?	❌ Missing piece	The application key cannot do this: it is one key for the whole bot. Laravel must mint a per-student, per-training token (JWT, 30 minutes) after checking ownership. Flutter sends that token to the bot; the bot verifies it offline. See §5.3.
5	I feed the RAG manually with `.md` files per training.	✅ Unchanged	Same upload flow; only the way you pick the training changes.
6	Save every conversation in the bot’s history with the email as the unique id.	⚠️ Nearly	Key conversations on the Laravel user id (`lms:123`) and store the email next to it as the display label. Emails are unique today but can be edited; the id never changes. The History page still shows and filters by email.
7	A default usage cap per user (tokens or questions per day), the same for everyone.	✅ Mostly there	The bot already counts questions per minute and per day (`usage_counters`) and tokens per answer (`messages.tokens`). Add a daily token budget, make the three limits editable in the bot admin, and return “questions left today” to Flutter so the panel can show it.
8	After adding the key, a Fetch trainings button fills a dropdown with names, slugs and ids.	✅ Correct, one change	The React admin must not hold the Laravel key in the browser. The button calls the bot backend, which calls Laravel with the key stored server-side, then caches the catalog in `trainings_ref`. The dropdown shows label · slug · id · company · public/private · AI on/off · number of documents.
9	The catalog tells the bot which trainings are public or not.	✅ Correct	Rows carry `is_public`, `published`, `is_active` (not archived or deleted) and `ai_assistant_enabled`. Private trainings keep the assistant: access is decided per student by ownership, not by `is_public`.
10	(implicit) Which value is the bot’s `training_id`: the Laravel id or the slug?	💡 Recommendation: the id	Slugs are editable (`POST /training/{id}`), so keying on them needs rename detection and a re-key routine (the 14/10 plan spent a whole section on it). The id is immutable and already what the course player route uses. The slug stays visible everywhere through the synced catalog. Decision #1 in §12.

3. What exists today (verified in the code)

LMS_ai_bot (FastAPI + pgvector + React admin)

Fact	Where
Every table is keyed by `training_id` (`String(64)`): documents, chunks, bot_configs, conversations.	`backend/app/models/tables.py`
Three auth paths: `ADMIN_API_KEY`, a JWT “signed by the LMS” (`LMS_JWT_SECRET`, falls back to `JWT_SECRET`), and the admin login session. Nothing issues LMS tokens yet.	`backend/app/core/security.py`, `backend/app/api/deps.py`
Chat routes authenticate the caller but do not yet check which training a token may use. The integration adds that check on every route (§9.2).	`backend/app/api/chat.py`
The conversation owner is recorded from the token’s `email` when present and compared with `sub` later. The integration settles on one owner key, `lms:<sub>`, for both.	`backend/app/api/chat.py`
LMS tokens and the bot’s own session tokens are verified with the same secret and the same claim rules. The integration verifies them separately (own secret, `iss` / `aud` / `typ`) and never lets an LMS token carry admin scope.	`backend/app/core/security.py`
`trainings_ref` (cached training name) is never written; prompts fall back to the raw id.	`backend/app/repositories/configs.py`, `backend/app/services/ingestion.py`
Rate limit per student: 15 questions/minute, 300/day, Postgres-backed. Tokens are counted per answer but there is no token budget.	`backend/app/services/guardrails.py`, `backend/app/services/llm.py`
`recent_turns()` exists but is never called: follow-up questions have no memory.	`backend/app/repositories/conversations.py`, `services/rag.py`
Admin UI: free-text “Training ID” (default `"1"`) and a manual “Admin token / key” field on Admin, Chat, Analytics. The login session already drives the API; the field is only an override.	`frontend/src/features/admin/AdminPage.tsx`, `lib/api.ts`
SSE streaming exists (`POST .../messages/stream`), answers are French or English only, conversations carry a `CONV-000042` reference.	`backend/app/api/chat.py`, `schemas/schemas.py`
`httpx` (HTTP client) and `cryptography` (via `python-jose`) are already installed: no new dependency for calling Laravel or encrypting settings.	`backend/requirements.txt`
Secrets-hygiene items for the bot repo are tracked privately (workspace plan §4).	`LMS_Project/AI_ASSISTANT_INTEGRATION.md`
The Plesk recipe exists (`proxy_buffering off` for SSE, systemd unit, pgvector install).	`hosting_in_plesk.md`

LMS_Backend (Laravel 12)

Fact	Where
Sanctum tokens never expire and carry every ability: they must never be forwarded to the bot.	`config/sanctum.php`
Ownership = paid order item: `orders.type = 3`, status 4 or 5, order not archived/deleted, `order_items.access_revoked = false`. Ready-made helper: `MarketplacePreviewService::ownedTrainingIds($user, [$id])`. Free assignments and vouchers create Paid-Offline orders at price 0, so the same rule covers them.	`app/Services/MarketplacePreviewService.php`
Do not use `users.owned_trainings` (JSON slug cache, goes stale) or `User::trainings()` (miswired join).	`LMS_Backend/CLAUDE.md` §12
`trainings.slug`: nullable, unique, server-generated, editable on update. `trainings.id` is immutable.	`app/Models/Training.php`
No machine-to-machine auth exists. The pattern to copy is `StorageInspectorController::authorizeAccess` (`hash_equals` on a header).	`app/Http/Controllers/StorageInspectorController.php`
`platform_settings` (`key` unique, `encrypted` flag with transparent encrypt/decrypt accessors) is a ready home for the bot URL and the signing secret.	`app/Models/PlatformSetting.php`
Roles: 5 = Super Admin (`isSuperAdmin()`); `CompanyPolicyMiddleware` lets super admins bypass the company check.	`app/Models/Role.php`, `app/Http/Middleware/CompanyPolicyMiddleware.php`
`ai_assistant_enabled` does not exist in the backend yet (frontend-only flag, Flutter Update 38).	grep of `app/` and `database/`
A few dev-only convenience routes still sit outside the auth groups. Locking them down is a Phase 0 item, tracked privately.	`LMS_Project/AI_ASSISTANT_INTEGRATION.md` §4
`jwt-auth` is installed but unused; HS256 signing is a few lines of native PHP, no package needed.	`composer.json`
Conventions: config in `config/custom_config.php`, inline `validate()`, errors as `{message}`, tests in `tests/Feature` with `tests/Support/CreatesLmsFixtures.php`.	`LMS_Backend/CLAUDE.md`

LMS_Frontend (Flutter)

Fact	Where
The assistant panel: `CoursePlayerAssistantPanel` (web side panel 320/380 px, phone end drawer) hosting `TrainingAiAssistantWidget`, a static mockup: seeded bubbles, disabled input, chips and Send show “coming soon”. Wiring points are marked `TODO(ai)`.	`lib/ui/pages/student_pages/training/training/course_player_assistant.dart`, `lib/ui/widgets/training/training_ai_assistant_widget.dart`
Per-training on/off toggle, frontend-only (SharedPreferences). The backend move is already written down in `major_code_updates.md` Update 38.	`lib/core/utils/resources/ai_assistant_local_settings.dart`
The open training (`id`, `slug`, `label`, `instructorId`), lesson and chapter are in `StudentTrainingProvider`.	`lib/core/providers/student_training_provider.dart`
One `Dio` built in `locator.dart` (Bearer + Accept-Language interceptor). Base URL hand-edited in `constants.dart` (TEST is active). No SSE code.	`lib/locator.dart`, `lib/core/constants/constants.dart`
`markdown` is in `pubspec.lock` through `flutter_quill`; `AppHtmlContent` renders HTML.	`pubspec.lock`
The super admin shell already has a platform configuration route: `/super-admin-admin-platform-configuration`.	`lib/core/routes/app_routes/super_admin_app_routes.dart`
App languages en / fr / ar; the bot answers in fr / en.	`assets/translations/`

4. Target architecture

Who talks to whom

The bot calls Laravel only for the catalog (admin actions), never during a chat.
Laravel never calls the bot. It only signs tokens the bot can verify offline.
Flutter talks to both: Laravel for the token, the bot for the chat. The bot’s public URL comes back with the token, so there is no new constant in constants.dart and switching Constants.baseUrl to another environment switches the bot too.
One bot instance per Laravel environment (test, prod): separate database, separate keys.

5. The three credentials

Credential	Format	Laravel side	Bot side
Application key	`lmsbot_<8 char prefix>_<40 hex>`	`ai_bot_api_keys`: `key_prefix` (indexed), `key_hash` = sha256, `scopes`, `last_used_at`, `revoked_at`	`integration_settings.lms_service_key` (Fernet-encrypted) or `LMS_SERVICE_KEY` env
Signing secret	64 hex (`random_bytes(32)`)	`platform_settings` key `ai_bot.jwt_secret`, `encrypted = 1`	`integration_settings.lms_jwt_secret` or `LMS_JWT_SECRET` env
Bot admin login	email + password	none	`users` + `auth_sessions` (exists)

The bot’s own JWT_SECRET (admin sessions) must be a different value from the signing secret. The bot should refuse to start outside development when the two are equal, and an LMS token must never grant bot-admin rights whatever it claims (§9.2).

5.1 Why the secrets live in the bot’s database and not only in `.env`

Your flow is “paste the key in the admin page, click Fetch”. The bot’s settings are read once at startup (get_settings() is cached), so an .env-only design would need an SSH restart every time you pair or rotate. A small integration_settings table (key, encrypted value) makes the UI flow work and .env stays as the override for production hosts that prefer it: when an env value is set, the UI shows the field as read-only.

5.2 Why a per-student token and not the application key

The application key identifies the bot, not a student. A chat request must prove (a) which user is asking and (b) that this user owns this training. Three ways to do it were compared:

Option	Verdict
A. Laravel mints a short-lived JWT per student and training; the bot verifies it offline	✅ Chosen. No Laravel call per message, least privilege (one training, 30 min), streaming works bot-to-client. Cost: a revoked student keeps a token for at most 30 min.
B. Flutter sends its Sanctum token to the bot, the bot asks Laravel on every message	❌ A never-expiring, all-powerful token reaches a third service, plus one Laravel round-trip per message.
C. Proxy the whole chat through Laravel	❌ PHP workers would hold SSE streams open. Laravel stays the gatekeeper, not the pipe.

5.3 The student token

Issued by POST /api/ai-assistant/trainings/{idOrSlug}/token (Sanctum, blocked-user and company middlewares), signed HS256 with the signing secret:

Claim	Value	Used by the bot for
`iss`	`lms-backend`	strict verification
`aud`	`lms-ai-bot`	strict verification
`typ`	`lms_student`	tells it apart from the bot’s own `session` tokens
`sub`	Laravel `users.id` as a string	owner key `lms:<sub>`, rate limit key
`tid`	Laravel `trainings.id` as a string	the only training this token may touch (`tid == training_id`)
`slg`	training slug	display only
`cid`	`company_id`	analytics, future per-company limits
`role`	`role_id`	History page shows who was testing
`name`, `email`	full name, email	`conversations.student_label`; the bot ignores any `scopes` / `is_admin` claim
`iat`, `exp`, `jti`	now, now + TTL, uuid	expiry, audit

Laravel refuses to mint when: the training is unknown, archived or deleted (404); it belongs to another company and the caller is not a super admin (404); ai_assistant_enabled is false (403 assistant_disabled); the caller does not own it (403 not_owned); the pairing is incomplete, no secret or no bot URL (503 assistant_not_configured). Recommended addition: company Admin, Super Admin and the training’s instructor also get a token so staff can test from the player (decision #2).

6. Flows

6.1 Pairing (once per environment)

The fingerprint is substr(sha256(secret), 0, 12). Laravel returns it in ping, the bot computes the same from the pasted secret and compares: you learn about a typo at pairing time, not from a student’s 401.

6.2 Feeding a training (unchanged, except the picker)

Pick the training

In the bot admin, the “Training ID” box becomes a searchable dropdown fed by GET /api/admin/lms/trainings. Each row shows the label, then slug · #id · company, badges for public/private, AI on/off, and the number of documents already uploaded. The selected value is the Laravel id.

Upload the Markdown

Same UploadDocs component: .md / .markdown / .txt, 10 MB max, re-uploading the same filename replaces its chunks. Ingestion now fills trainings_ref from the catalog so prompts and the fallback message use the training label from the first upload.

Tune the bot (optional)

System prompt, model, temperature, top-k, similarity threshold: unchanged GuardrailEditor.

Students can ask

Any student who owns that training, when ai_assistant_enabled is true in Laravel.

6.3 A student asks a question

6.4 Revocation, renames and quotas

Access revoked or refunded (access_revoked = true): Laravel stops minting at once; a token already issued works until it expires (30 min at most). Lower the TTL to shrink the window.
Assistant switched off for a training: same, 30 min at most. The Flutter header shows the Off pill from the training payload right away.
Slug renamed: nothing to do. The bot is keyed on the id; the next sync refreshes the slug shown in the dropdown.
Quota reached: the bot answers 429 with the scope (minute, day, tokens) and resets_at; the panel shows the message and keeps the history readable.

7. Data model changes

7.1 Laravel

ai_bot_api_keys: one migration. Lookup by key_prefix, then hash_equals on the hash; last_used_at updated at most once a minute (no write per request).
platform_settings: no migration, three rows with company_id = null.
trainings.ai_assistant_enabled: boolean default true, $fillable, nullable|boolean on POST /training/{id} guarded by request()->has(), present in GET /training/{id}, GET /trainings, GET /preview-training/{idOrSlug} and the student’s my_trainings[] cards (AuthUserPayloadService, whitelist-based: add the field there).

7.2 Bot (Alembic `0004_lms_integration`)

training_id stays String(64): a Laravel id fits, so the column widening of the 14/10 plan is dropped. bot_limits can be three rows of integration_settings instead of a table.

8. Quotas (your “default usage per user”)

Limit	Default	Who sees it	Why
Questions per minute	10	nobody (429 only)	anti-abuse
Questions per day	60	students: “N questions left today” under the composer	predictable for learners
Tokens per day	450 000	admin analytics only	the real cost guard: a question costs about 7 k tokens (§16, Q5), so 60 questions are about 420 k

Defaults live in the bot, editable in a “Limits” card of the admin page. They apply to every student of every training (what you asked for). Per-training overrides can come later through bot_configs.
The bot enforces both counters before calling the LLM and adds the answer’s tokens after. The MessageOut and the status response gain a usage object: questions_left_today, tokens_left_today, resets_at. The 429 body is {"code": "quota_exceeded", "scope": "day", "resets_at": "..."}.
Later, Laravel can override the defaults per company or per plan with a lim claim in the token; the bot would read it when present. Not needed for v1.

9. API contract summary

9.1 New in LMS_Backend

Method and path	Auth	Purpose
`GET /api/ai-bot/ping`	`X-AI-Bot-Key`	`{ok, key_label, scopes, signing_secret_fingerprint, app_version}`
`GET /api/ai-bot/trainings`	`X-AI-Bot-Key`, `throttle:ai-bot` (60/min)	Paginated catalog. Query: `search`, `company_id`, `updated_since`, `include_inactive=1`, `per_page` (max 200). Row: `id, slug, label, company_id, company_label, is_public, published, is_active, ai_assistant_enabled, updated_at`. Never a model, never lesson content or instructor PII.
`GET /api/ai-bot/trainings/{id}`	same	One row, 404 `{message}` otherwise
`POST /api/ai-assistant/trainings/{idOrSlug}/token`	Sanctum group, `throttle:20,1`	Student (or staff) token, see §5.3. POST because it mints a credential.
`GET /api/ai-assistant/admin/keys`	Sanctum, `isSuperAdmin()`	List keys (prefix, label, scopes, last used, revoked)
`POST /api/ai-assistant/admin/keys`	same	`{label, expires_at?}`; answers the plain key once
`DELETE /api/ai-assistant/admin/keys/{id}`	same	Revoke (sets `revoked_at`)
`GET /api/ai-assistant/admin/settings`	same	`{public_url, token_ttl_minutes, has_signing_secret, signing_secret_fingerprint}`
`PUT /api/ai-assistant/admin/settings`	same	`{public_url, token_ttl_minutes}`
`POST /api/ai-assistant/admin/signing-secret/rotate`	same	New secret, answered once with its fingerprint. Rotating invalidates every live student token (30 min of 401s at most, Flutter refreshes).

Code lives in app/Http/Controllers/AiBotController.php (catalog), AiAssistantController.php (token + super admin management), app/Http/Middleware/VerifyAiBotApplicationKey.php (alias ai_bot_key), app/Support/AiBotToken.php (native HS256 encode, refuses secrets under 32 bytes), config/custom_config.php for issuer / audience. Tests: tests/Feature/AiBotCatalogTest.php, AiAssistantTokenTest.php, AiBotAdminKeysTest.php.

9.2 Changed or new in LMS_ai_bot

Method and path	Auth	Change
every `/api/chat/*` route	LMS token or bot admin	`ensure_training_access(principal, training_id)`: admins pass; an LMS token passes only when `tid == training_id` (the path id, `payload.training_id`, or `convo.training_id` on every message). 403 `training_access_denied` otherwise.
`GET /api/chat/trainings/{tid}/status`	same	New. `{training_id, name, slug, has_content, documents, usage}`
`GET /api/chat/me/usage`	same	New. Remaining quota for the caller
`POST /api/chat/sessions`	same	Owner key `lms:<sub>` in `student_ref`, email in `student_label`: one owner key everywhere
`POST .../messages`, `.../messages/stream`	same	Quota check (minute, day, tokens), `usage` in the answer, 429 body with `scope` and `resets_at`; `recent_turns()` finally passed to the prompt (6 turns)
`GET /api/admin/lms/settings`, `PUT`	bot admin	New. LMS API URL, key and secret (masked when read); env values shown read-only
`POST /api/admin/lms/test`	bot admin	New. Calls Laravel `ping`, compares the secret fingerprint
`GET /api/admin/lms/trainings?search=&company_id=`	bot admin	New. Catalog from `trainings_ref` merged with local counts (`documents`, `chunks`, `has_content`). Feeds the dropdown. The key never reaches the browser.
`POST /api/admin/lms/sync`	bot admin	New. Pages through the Laravel catalog with `include_inactive=1`, upserts `trainings_ref`, answers `{created, updated, deactivated}`
`GET /api/admin/limits`, `PUT`	bot admin	New. The three quota defaults
`GET /api/admin/trainings/{tid}/conversations`, analytics	bot admin	Show `student_label`, training label and slug instead of raw ids

Token verification (core/security.py): decode_lms_token checks iss, aud, typ, exp, iat, sub, tid with the signing secret only; is_admin is always False for LMS tokens; Principal gains training_id, display_name, email. try_decode tries the bot’s own session secret first, then the LMS secret. Startup guard: refuse to boot outside development when the secret is empty or equals JWT_SECRET.

9.3 Error codes the Flutter panel maps to a state

Response	Panel state	Copy (en, to translate fr / ar)
Laravel 403 `not_owned`	`notOwned`	”Enroll in this training to use its AI assistant”
Laravel 403 `assistant_disabled`	`disabled` (existing Off panel)	“AI assistant is not available here”
Laravel 404	`unavailable`	”Assistant not available for this training”
Laravel 503 `assistant_not_configured`	`unavailable`	”Assistant temporarily unavailable” + Retry
Bot `has_content: false`	`noContent`	”The instructor hasn’t added material to the assistant yet”
Bot 401 after one refresh, or unreachable	`unavailable`	”Assistant temporarily unavailable” + Retry
Bot 429	`quotaExceeded`	”You’ve reached today’s question limit, back at HH:MM”
Answer with `fallback: true`	normal bubble, muted style	”Not found in the course material” footnote

10. Phased plan

Phase 0 · Prerequisites (do first, half a day)

Security prerequisites, tracked privately in LMS_Project/AI_ASSISTANT_INTEGRATION.md §4 (this site is public): lock down the dev-only routes of LMS_Backend (behind APP_ENV=local
- a token, like the storage inspector) and finish the secrets-hygiene pass on both repos’ example files. Git history keeps old values, so rotation is what matters, not deletion.
Workspace: add LMS_ai_bot/ to the root .gitignore with a .gitkeep, and add LMS_ai_bot > / ai_bot > to the prompt-prefix table of the root CLAUDE.md.
Bot branch: decide where the integration lands (master, or a new lms-integration branch from before-integration).

Phase 1 · LMS_Backend (Laravel), 2 days

Migrations: create_ai_bot_api_keys_table, add_ai_assistant_enabled_to_trainings_table.
Model AiBotApiKey (generate(): [plain, model], verify(plain)), Training::$fillable
- casts, PlatformSetting rows for ai_bot.*.
Middleware VerifyAiBotApplicationKey (header only, prefix lookup, hash_equals, revoked and expiry checks, last_used_at throttled), RateLimiter::for('ai-bot').
AiBotController: ping, trainings, training. Whitelisted arrays, whereNotNull('slug') not required any more (id-keyed), withoutGlobalScope('archived')->withTrashed() only with include_inactive=1, eager-load company:id,label (strict mode).
AiAssistantController: token (§5.3) and the super-admin keys, settings, rotateSigningSecret; every method starts with isSuperAdmin() except token.
AiBotToken::encode() (native HS256). config/custom_config.php ai_bot.issuer / ai_bot.audience.
TrainingsController@update: accept ai_assistant_enabled; AuthUserPayloadService and MarketplacePreviewService::trainingCard expose it.
Tests (SQLite, fixtures): owner Paid-Online 200 and the token decodes; Paid-Offline at 0 TND 200; Pending / Cancelled / Failed / revoked / Cart / Wishlist 403; other company 404; archived or deleted 404; disabled 403; not paired 503; blocked user; catalog 401 without header, 401 revoked, 200 whitelisted rows; super-admin-only management (admin gets 403).
insert_in_history_table on key creation, revocation and secret rotation.

Phase 2 · LMS_ai_bot backend (FastAPI), 2 to 3 days

Phase 3 · LMS_ai_bot admin UI (React), 1 to 2 days

“LMS connection” card on /admin: LMS API URL, application key, signing secret (masked), Test connection, Fetch trainings (sync) with the result and “last synced” time.
TrainingPicker combobox (search, label · slug · #id · company, badges) replacing the free text on Admin, Chat, History, Analytics. Stores the id.
“Limits” card (three numbers). History and Analytics show emails and training labels.
Hide the manual “Admin token / key” field behind a “Developer” toggle, or remove it: the login session already authenticates the UI.
Chat page keeps working as your test console (the admin session bypasses the training check).

Phase 4 · LMS_Frontend student side (Flutter), 3 days

api_client.dart: @POST('/ai-assistant/trainings/{idOrSlug}/token') + model AiAccessToken (token, expiresAt, aiBaseUrl, training, limits); build_runner.
lib/core/services/ai_assistant/ai_bot_client.dart: a second Dio (10 s connect, 90 s receive, no Sanctum interceptor), base URL from the token response, Bearer AI token, one silent refresh on 401. Retrofit client AiBotApiClient for status, seances, sessions, messages, me/usage. Models under lib/core/data/remote/ai_assistant/.
AiAssistantProvider (ChangeNotifier, locator.dart + providers.dart): states idle · loading · ready · notOwned · disabled · noContent · unavailable · quotaExceeded · error; openFor(training), send(text), newConversation(); token cached per training and refreshed 60 s before expiry; session id per training in SharedPreferences (aiAssistantSession_<id>), history reloaded on open, forgotten on 403 / 404; no session created until the first message.
Wire training_ai_assistant_widget.dart: live messages, chips built from the current lesson and chapter plus the bot’s seances, Send, New conversation, input enabled when ready, “N questions left today” line, sources as small chips, Markdown rendered through markdownToHtml() + AppHtmlContent (promote markdown to a direct dependency, same version, nothing new downloaded).
course_player_assistant.dart: read training.aiAssistantEnabled from the payload instead of AiAssistantLocalSettings; call openFor when the panel opens.
Language: en → "en", fr → "fr", ar → null (auto) with a one-line note.
Translations en / fr / ar for the §9.3 states; fix the Off pill reusing the discount off key (“Rem.” in French, “خصم” in Arabic).
Append the entry to major_code_updates.md.

Phase 5 · LMS_Frontend admin and super admin (Flutter), 1 to 2 days

Super admin: an AI Assistant section on the platform configuration page (/super-admin-admin-platform-configuration) or a sibling route: bot URL, token TTL, signing secret (Rotate, shown once with Copy), application keys table (label, prefix, last used, Revoke) and Generate (shown once with Copy). Retrofit methods for the §9.1 admin routes.
Admin trainings: TrainingProvider.toggleAiAssistantForTraining sends ai_assistant_enabled to POST /training/{id} and re-fetches, as Update 38 planned; delete ai_assistant_local_settings.dart and its test; re-add the field to the Training model.

Phase 6 · LMS_Documentation, half a day

api-reference/ai-assistant.mdx: the student token endpoint, the super admin management endpoints and the service-key catalog, with request and response examples; register it in docs.json and add the two controllers to the controller-to-page map in CLAUDE.md.
api-reference/trainings.mdx: the ai_assistant_enabled field on create, update, show, list and preview.
system-design/class-diagram.mdx: AiBotApiKey and the new Training column.
Changelog mirrors once the Flutter entries exist.

Phase 7 · Later

Streaming answers. The bot already streams. Mobile: Dio with ResponseType.stream. Web (the main target): XHR gives the body only at the end, so a small fetch + ReadableStream reader through dart:js_interop behind a conditional import; no new package.
Conversation list per student and training (GET /api/chat/sessions?training_id=) for a “previous conversations” menu.
Arabic in the bot’s language gate and prompts.
Per-company or per-plan quotas through the lim claim.
Feeding from Laravel: a “Course material for the assistant” upload in the Flutter admin that pushes .md files to the bot through a Laravel proxy, so instructors never need the React admin.
Analytics in Flutter: the bot’s per-training analytics shown on the admin training page.

11. Settings checklist

Where	Setting	Value
Laravel `platform_settings`	`ai_bot.public_url`	Local `http://localhost:8000`; TEST the bot’s public URL
Laravel `platform_settings`	`ai_bot.jwt_secret` (encrypted)	generated by Rotate
Laravel `platform_settings`	`ai_bot.token_ttl_minutes`	`30`
Laravel `config/custom_config.php`	`ai_bot.issuer`, `ai_bot.audience`	`lms-backend`, `lms-ai-bot`
Bot `integration_settings` or env	`lms_api_url` / `LMS_API_URL`	Local, bot in Docker + `artisan serve` on the host: `http://host.docker.internal:8020/api`; TEST: `https://backend-test.theteam.com.tn/api`
Bot	`lms_service_key` / `LMS_SERVICE_KEY`	the application key
Bot	`lms_jwt_secret` / `LMS_JWT_SECRET`	the signing secret, different from `JWT_SECRET`
Bot `.env`	`JWT_SECRET`	its own random value (admin sessions)
Bot `.env`	`ADMIN_API_KEY`	rotate away from `dev-admin-key`; unset in production
Bot `.env`	`CORS_ORIGINS`	`http://localhost:5000` + the Flutter web domains
Bot `.env`	`OPENAI_API_KEY`	required even with Gemini as chat provider (embeddings)
Flutter	none	the bot URL comes with the token

12. Decisions to confirm before coding

#	Question	Recommendation
1	Bot `training_id` = Laravel id or slug?	id. Immutable, already the route parameter, no re-key logic. The slug is displayed everywhere from the synced catalog. Existing sample data keyed `"1"` moves with one SQL update to the real id.
2	Who gets a token: owning students only, or also same-company Admin / Super Admin and the training’s instructor?	Owners plus staff, so you can test from the course player without buying the training. Staff get a plain chat token, never bot-admin rights.
3	Token TTL	30 minutes
4	Quota defaults and what students see	10 / min, 60 / day, 450 k tokens / day; students see questions left, tokens stay internal
5	Secrets in the bot: database (UI flow) with env override, or env only?	Database with env override
6	Blocking answers in v1, streaming later?	Yes: v1 blocking, streaming in Phase 7
7	Arabic: auto-detect + note, or extend the bot’s gate?	Note for v1
8	Promote `markdown` to a direct dependency to render answers?	Yes, no new download
9	Pull `ai_assistant_enabled` into Phase 1 (it was “later” in the 14/10 plan)?	Yes: one column, and the toggle UI already exists
10	Bot repo branch for the work	new `lms-integration` branch from `before-integration`, merged to `master` when the acceptance list passes

13. What changed since the 14/10/2026 plan

Topic	14/10 plan	This page
Bot key	training slug, with rename detection, a re-key endpoint and a column widening	Laravel id; slug cached for display
Secrets	two `.env` variables set by hand on each side	generated from the super admin dashboard, stored hashed / encrypted in Laravel, pasted once into the bot admin, verified by `ping` + fingerprint; `.env` stays as override
`email` claim	left out, so the bot would not record it as the owner	kept for the History label; the owner key is `sub` only
Quotas	existing request limits only	+ daily token budget, editable defaults, `usage` returned to Flutter
`ai_assistant_enabled`	Phase 4	Phase 1
Staff access for testing	to confirm	recommended
Admin “Training ID” box	searchable combobox by slug	searchable combobox by id, with public / AI / documents badges

14. End-to-end acceptance

curl -H "X-AI-Bot-Key: <key>" $LARAVEL/api/ai-bot/ping answers ok and the fingerprint; without the header or with a revoked key it answers 401.
In the bot admin, Test connection says “signing secret matches”, Fetch trainings lists the catalog with public / private and AI badges. Pick one, upload .md files, status ready.
A student who owns the training asks a question in the course player: grounded answer with sources, “59 questions left today”, and the bot History shows the student’s email and the training label.
A student who does not own it gets 403 from the token endpoint and the panel’s enroll state.
Reuse student A’s token on another training id: 403. Reuse it after 30 minutes: 401, refreshed silently once.
Revoke the student’s access or switch the assistant off: the token endpoint refuses at once; the assistant stops within one TTL.
Rename the training’s slug, run Fetch trainings: the dropdown shows the new slug, documents and conversations are untouched.
Rotate the signing secret in the super admin page and paste it in the bot: live tokens fail with 401 until refreshed, new tokens work.
Ask the 61st question of the day: 429, the panel shows the reset time, history still readable.
Arabic UI: questions accepted with auto-detect, the language note is shown.

15. Suggested order of prompts

The root CLAUDE.md scopes work by repo prefix, so each step is one prompt:

Backend > Phase 0 (debug routes, placeholders) then Phase 1.
Documentation > Phase 6 (the API pages can be written from the Phase 1 code).
LMS_ai_bot > Phase 2, then Phase 3 (add the prefix to the root CLAUDE.md first).
Frontend > Phase 5 first (pairing page + backend toggle, small), then Phase 4 (student panel).
Phase 7 items one at a time.

16. Questions and answers (04/11/2026)

Questions raised while reviewing the plan, with the answers and the reasoning behind them.

Q1. What is the latency of a student question, end to end?

Measured on the local Docker stack (this Mac, 04/11/2026):

Call	Measured	What it shows
`GET /api/health`	3 ms	FastAPI overhead
`POST /api/chat/sessions`	14 ms	one Postgres insert and commit
`POST .../messages` up to the retrieval step	14 ms	auth, session load, rate limit, DB reads

The LLM step could not be measured here: the local database holds no documents and no conversations, OPENAI_API_KEY is empty (embeddings need it, so every semantic question answers 500), the configured chat model gemini-1.5-flash was shut down by Google on 29/09/2025, and the Google key in backend/.env is rejected by Google (“API key not valid”). The bot has never answered a question on this machine. Before measuring: set an OpenAI key, move GOOGLE_CHAT_MODEL to gemini-2.5-flash-lite or switch LLM_PROVIDER, and restart the backend. Estimated budget per hop (typical values for a bot hosted in Europe, students in Tunisia):

Hop	Typical	Note
Flutter to Laravel, `POST .../token`	150 to 400 ms	once per 30 minutes per training; 2 or 3 SQL queries plus HS256 signing
Flutter to bot, `GET .../status`	60 to 150 ms	one count query; once per panel opening
Bot: auth, session, quota	10 to 20 ms	measured above
Question embedding (OpenAI `text-embedding-3-small`)	100 to 300 ms	one HTTPS call from the bot’s server
pgvector top-k search	5 to 30 ms	a few thousand chunks per training
LLM generation, about 450 tokens	1.5 to 5 s on Haiku 5.5, gpt-5-mini or Gemini 2.5 Flash-Lite; 4 to 8 s on a Sonnet-class model	the dominant cost; first token after 0.4 to 1.5 s
Persist the two messages	10 to 20 ms
Network, student to bot	40 to 80 ms per round trip	Tunisia to a European host
Flutter: decode JSON, Markdown to HTML, rebuild	5 to 30 ms	the app is not the bottleneck

Totals. A question in blocking mode (v1) takes about 2 to 6 seconds (2 000 to 6 000 ms) wall clock, of which more than 90 % is the model writing its answer. The first question after opening the panel adds about half a second (token, status, session). The Flutter side adds well under 100 ms. With streaming (Phase 7) the first words appear after about 1 to 1.5 s and the rest flows in. How to measure for real. Every answer stores messages.latency_ms (the bot’s internal time, embedding plus generation); GET /api/admin/trainings/{id}/analytics returns avg_latency_ms. Add a stopwatch log around send() in the Flutter provider: the difference between the two is the network share. Levers if it feels slow: a smaller model, top_k 4 instead of 6, max_tokens 500, streaming, and hosting the bot next to Laravel so the student pays one European round trip.

Q2. How does the bot know which students own a training?

It does not, and it never needs to. Ownership is a Laravel task. The bot only trusts the token Laravel issues:

The course player asks Laravel for a token for training 42 (Sanctum session).
Laravel checks the paid order item (MarketplacePreviewService::ownedTrainingIds), the company, and ai_assistant_enabled, then signs a token with tid = "42" for 30 minutes.
The bot verifies the signature with the shared secret and, on every chat call, compares tid with the training of the session or path. No Laravel call, no ownership table in the bot.

Why not the alternatives: asking Laravel on every message costs a round trip per question and would send the never-expiring Sanctum token to a third service; copying an ownership list into the bot duplicates data that changes with every order, refund or voucher and goes stale (the catalog sync is for trainings, not students). The cost of the chosen design is the revocation window: a student whose access is revoked keeps working for at most the remaining token lifetime.

Q3. How to fix the three flagged points

A. “The application key replaces dev-admin-key” (two different keys).

Step	Where	What
1	Bot `core/security.py`	`principal_from_admin_key` returns `None` when `ADMIN_API_KEY` is empty. Production `.env` leaves it empty; development keeps a random value.
2	Bot React admin	Remove the “Admin token / key” field from Admin, Chat and Analytics (or move it behind a “Developer” switch in Profile). The login session already drives every call (`lib/api.ts`).
3	Bot	New `integration_settings` table and an “LMS connection” card: LMS API URL, application key, signing secret, Test connection, Fetch trainings. Values encrypted with Fernet, key derived from `JWT_SECRET`. The browser never sees the application key: the bot backend calls Laravel.
4	Laravel	`ai_bot_api_keys` table, `VerifyAiBotApplicationKey` middleware, super-admin endpoints (§9.1). Key format `lmsbot_<prefix>_<secret>`, sha256 stored, shown once.
5	Flutter super admin	Generate, copy once, revoke; set the bot URL and the token TTL (§10 Phase 5).

Result: three credentials, each with one job (§5). Nothing of the old flow is lost; the dev key simply stops being the way you log in. B. “How a student proves identity and ownership to the bot.”

Step	Where	What
1	Laravel `AiAssistantController::token`	`POST /api/ai-assistant/trainings/{idOrSlug}/token` behind Sanctum. Ownership through orders, company check, `ai_assistant_enabled`, then a 30-minute HS256 token with the claims of §5.3. 403 or 404 with a `code` otherwise.
2	Bot `core/security.py`	`decode_lms_token`: verify with the signing secret, require `iss`, `aud`, `typ = lms_student`, `exp`, `sub`, `tid`; `is_admin` always false.
3	Bot `api/deps.py` + `api/chat.py`	`ensure_training_access(principal, training_id)` on every chat route, compared with the session’s training, not only at session creation.
4	Flutter `AiBotClient`	Second Dio, Bearer AI token, one silent refresh on 401 then retry; the panel maps 403 / 404 / 429 to its states (§9.3).
5	Tests	Token for 42 cannot touch 43; expired, wrong audience, wrong secret give 401; an LMS token claiming admin scope still gets 403 on `/api/admin/*`.

C. “Email as the unique id.”

Step	Where	What
1	Bot `api/chat.py`	One helper `owner_key(principal)` returning `lms:<sub>`, used by `start_session` and `_load_session` (today one stores the email, the other compares the subject).
2	Bot migration `0004`	`conversations.student_label` (email, falls back to the name) next to `student_ref`.
3	Bot History page	Show and filter by `student_label`; the id stays the join key.
4	Rate limits and quotas	Already keyed on `student_ref`, so they follow the user id automatically.

Side benefit: if a student asks for their data to be removed, the label column can be blanked without breaking any key.

Q4. “Token lifetime 30 minutes”: which token?

The word is used for four different things in this plan:

Token	Issued by	Lifetime	Where it travels
Student AI access token (the one that lives 30 minutes)	Laravel, `POST .../token`	30 min, refreshed silently by Flutter	Flutter to the bot only
Sanctum login token	Laravel, `POST /auth/login`	never expires	Flutter to Laravel only, never to the bot
Application key	Laravel super admin page	until revoked (optional expiry)	bot backend to Laravel only
LLM tokens	the model provider	not a credential: the pieces of text providers bill for	the bot to the provider; §8 and Q5 count these

30 minutes is the trade-off between revocation delay (a revoked student keeps the assistant for at most 30 minutes) and refresh traffic (one small Laravel call per half hour per training).

Q5. Token consumption and cost: 10 vs 100 students, and how long 10 USD lasts

One question, measured with the bot’s own tokenizer (cl100k_base) on 04/11/2026:

Part of the prompt	Tokens	Source
System prompt (base rules + default admin prompt, French lock)	862	measured
Retrieved context, `top_k` 6 chunks of up to 800 tokens	up to 4 800	`CHUNK_SIZE_TOKENS` × `DEFAULT_TOP_K`
Question wrapper and the question itself	about 90	measured 37 + question
Conversation memory, 6 turns (Phase 2)	about 750	estimate
Input per question	about 6 500
Answer	about 450 (cap `DEFAULT_MAX_TOKENS` 800)
Question embedding	about 50	`text-embedding-3-small`, negligible cost

Tokens per day:

Scenario	Questions / day	Input tokens / day	Output tokens / day
10 students, typical 8 questions each	80	0.52 M	0.04 M
100 students, typical 8 questions each	800	5.2 M	0.36 M
10 students maxing the 60 / day cap	600	3.9 M	0.27 M
100 students maxing the 60 / day cap	6 000	39 M	2.7 M

Cost per model (list prices per million tokens, USD; “d” = how many days 10 USD last in that scenario):

Model	$ / M in · out	$ per question	Questions for $10	10 typical	100 typical	10 maxed	100 maxed
Claude Haiku 5.5	0.10 · 0.50	0.00087	11 400	$0.07/day · 143 d	$0.70/day · 14 d	$0.52/day · 19 d	$5.25/day · 1.9 d
Claude Sonnet 5.5	2.00 · 10.00	0.0175	570	$1.40/day · 7 d	$14/day · 0.7 d	$10.50/day · 1 d	$105/day · 0.1 d
Claude Opus 5.5	4.00 · 20.00	0.035	285	$2.80/day · 3.6 d	$28/day · 0.4 d	$21/day · 0.5 d	$210/day · 0.05 d
gpt-5-nano	0.05 · 0.40	0.00051	19 800	$0.04/day · 248 d	$0.40/day · 25 d	$0.30/day · 33 d	$3.03/day · 3.3 d
gpt-5-mini	0.25 · 2.00	0.0025	3 960	$0.20/day · 50 d	$2.02/day · 5 d	$1.51/day · 6.6 d	$15.15/day · 0.7 d
Gemini 2.5 Flash-Lite	0.10 · 0.40	0.00083	12 000	$0.07/day · 151 d	$0.66/day · 15 d	$0.50/day · 20 d	$4.98/day · 2 d
Gemini 2.5 Flash	0.30 · 2.50	0.0031	3 250	$0.25/day · 41 d	$2.46/day · 4 d	$1.84/day · 5.4 d	$18.45/day · 0.5 d
DeepSeek V4.1 Flash, peak hours	0.30 · 1.20	0.0025	4 000	$0.20/day · 50 d	$1.99/day · 5 d	$1.49/day · 6.7 d	$14.94/day · 0.7 d
DeepSeek V4.1 Flash, off-peak	0.15 · 0.60	0.0012	8 000	$0.10/day · 100 d	$1.00/day · 10 d	$0.75/day · 13 d	$7.47/day · 1.3 d

Embeddings are not in the table because they do not matter: a question costs about one ten-thousandth of a cent, and ingesting a 300 000-token training costs about 0.6 cent once. Recommendations

Anthropic: claude-haiku-5-5 for the answers. Grounded question answering over supplied context is its home ground, and it is 20 times cheaper than Sonnet. claude-sonnet-5-5 is the quality step for a premium training; claude-opus-5-5 is the general default elsewhere but 40 times the price of Haiku for this job. Prices from the Claude API reference (06/10/2026); Haiku’s rate applies to prompts under 100 K tokens, ours are about 7 K.
OpenAI: gpt-5-mini for quality, gpt-5-nano when cost matters most. Prices come from aggregator sites and must be checked on OpenAI’s pricing page before relying on them.
DeepSeek: V4.1 Flash. The old deepseek-chat id was retired in July 2026, prices halve outside its UTC peak hours (which overlap Tunisian mornings), and the bot does not know DeepSeek yet: its API is OpenAI-compatible, so one ChatOpenAI(base_url=...) branch in services/llm.py adds it. Course content and student questions would be processed on servers in China; weigh that before choosing it. Prices from aggregators that disagree with each other, verify first.
Google: Gemini 2.5 Flash-Lite costs the same as Haiku 5.5. The current configuration must change anyway (Q1).
Keep OPENAI_API_KEY set whatever the chat provider: embeddings always use OpenAI.
Prompt caching will not save much here: the stable prefix (862 tokens) is under the minimum cacheable size of most providers and the retrieved chunks change with every question. Expect 10 % at best; not worth engineering now.

So how long does 10 USD last? With Haiku 5.5 or Gemini 2.5 Flash-Lite, 10 USD buys about 11 000 to 12 000 questions: 10 students for about five months, or 100 students for about two weeks of typical use. If 100 students all hit the 60-question cap every day, 10 USD lasts two days, which is exactly why the daily cap exists. With gpt-5-nano the figures roughly double; with a Sonnet-class model they shrink by 20. The 450 000 tokens-per-day default in §8 follows from this: 60 questions × 7 000 tokens.

​1. The goal in one paragraph

​2. Your mental model, checked

​3. What exists today (verified in the code)

​LMS_ai_bot (FastAPI + pgvector + React admin)

​LMS_Backend (Laravel 12)

​LMS_Frontend (Flutter)

​4. Target architecture

​5. The three credentials

​5.1 Why the secrets live in the bot’s database and not only in .env

​5.2 Why a per-student token and not the application key

​5.3 The student token

​6. Flows

​6.1 Pairing (once per environment)

​6.2 Feeding a training (unchanged, except the picker)

​6.3 A student asks a question

​6.4 Revocation, renames and quotas

​7. Data model changes

​7.1 Laravel

​7.2 Bot (Alembic 0004_lms_integration)

​8. Quotas (your “default usage per user”)

​9. API contract summary

​9.1 New in LMS_Backend

​9.2 Changed or new in LMS_ai_bot

​9.3 Error codes the Flutter panel maps to a state

​10. Phased plan

​Phase 0 · Prerequisites (do first, half a day)

​Phase 1 · LMS_Backend (Laravel), 2 days

​Phase 2 · LMS_ai_bot backend (FastAPI), 2 to 3 days

​Phase 3 · LMS_ai_bot admin UI (React), 1 to 2 days

​Phase 4 · LMS_Frontend student side (Flutter), 3 days

​Phase 5 · LMS_Frontend admin and super admin (Flutter), 1 to 2 days

​Phase 6 · LMS_Documentation, half a day

​Phase 7 · Later

​11. Settings checklist

​12. Decisions to confirm before coding

​13. What changed since the 14/10/2026 plan

​14. End-to-end acceptance

​15. Suggested order of prompts

​16. Questions and answers (04/11/2026)

​Q1. What is the latency of a student question, end to end?

​Q2. How does the bot know which students own a training?

​Q3. How to fix the three flagged points

​Q4. “Token lifetime 30 minutes”: which token?

​Q5. Token consumption and cost: 10 vs 100 students, and how long 10 USD lasts

1. The goal in one paragraph

2. Your mental model, checked

3. What exists today (verified in the code)

LMS_ai_bot (FastAPI + pgvector + React admin)

LMS_Backend (Laravel 12)

LMS_Frontend (Flutter)

4. Target architecture

5. The three credentials

5.1 Why the secrets live in the bot’s database and not only in `.env`

5.2 Why a per-student token and not the application key

5.3 The student token

6. Flows

6.1 Pairing (once per environment)

6.2 Feeding a training (unchanged, except the picker)

6.3 A student asks a question

6.4 Revocation, renames and quotas

7. Data model changes

7.1 Laravel

7.2 Bot (Alembic `0004_lms_integration`)

8. Quotas (your “default usage per user”)

9. API contract summary

9.1 New in LMS_Backend

9.2 Changed or new in LMS_ai_bot

9.3 Error codes the Flutter panel maps to a state

10. Phased plan

Phase 0 · Prerequisites (do first, half a day)

Phase 1 · LMS_Backend (Laravel), 2 days

Phase 2 · LMS_ai_bot backend (FastAPI), 2 to 3 days

Phase 3 · LMS_ai_bot admin UI (React), 1 to 2 days

Phase 4 · LMS_Frontend student side (Flutter), 3 days

Phase 5 · LMS_Frontend admin and super admin (Flutter), 1 to 2 days

Phase 6 · LMS_Documentation, half a day

Phase 7 · Later

11. Settings checklist

12. Decisions to confirm before coding

13. What changed since the 14/10/2026 plan

14. End-to-end acceptance

15. Suggested order of prompts

16. Questions and answers (04/11/2026)

Q1. What is the latency of a student question, end to end?

Q2. How does the bot know which students own a training?

Q3. How to fix the three flagged points

Q4. “Token lifetime 30 minutes”: which token?

Q5. Token consumption and cost: 10 vs 100 students, and how long 10 USD lasts