yamen/full_encoach_platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(platform): ship AI fallback stack and entity-scoped course planning

Browse Source 
Unifies the new LangGraph-driven course-plan/media flow with robust provider fallbacks, admin AI provider settings, editable book-style materials, and strict entity isolation across LMS/course-plan APIs. Adds admin-only entity membership management in the Entities UI so users can switch linked entities directly from the platform.

Made-with: Cursor
This commit is contained in:
Yamen Ahmad
2026-04-26 02:34:52 +04:00
parent 096b042daf
commit 35ccc0dfb2
51 changed files with 5487 additions and 538 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/PROJECT_SUMMARY.md
View File

@@ -1,10 +1,14 @@
# EnCoach Platform — Project Summary
> Last updated: 2026-04-25 | **Canonical repos: [`encoach_backend_v4`](https://git.albousalh.com/devops/encoach_backend_v4) (backend) + [`encoach_frontend_v4`](https://git.albousalh.com/devops/encoach_frontend_v4) (frontend), branch `main`.**
> Last updated: 2026-04-26 | **Canonical repos: [`encoach_backend_v4`](https://git.albousalh.com/devops/encoach_backend_v4) (backend) + [`encoach_frontend_v4`](https://git.albousalh.com/devops/encoach_frontend_v4) (frontend), branch `main`.**
>
> This workspace (`odoo19/`) is a **developer monorepo / working tree only** — it conveniently contains both halves side-by-side for local development and testing. The two split repos above are the **authoritative origins** for each half: every change must be published to them (via `git subtree split + push`) before the team lead can deploy. See **§6 Git Remotes & Repositories** for the exact workflow.
> **Latest events:**
> - **2026-04-26 (admin-only entity membership management UI):** Added end-to-end UI flow for linking users to entities directly from `Admin -> Entities` (admin only). New backend routes in `encoach_exam_template/controllers/entities.py`: `GET /api/entities/<entity_id>/users` and `PATCH /api/entities/<entity_id>/users` (payload `{ user_ids: [...] }`) with strict admin guard (`base.group_system` / `base.group_erp_manager` / `user_type=admin`). `EntitiesPage` now includes a **Manage Users** action (`UserCog`) opening a searchable multi-select dialog, and `entities.service.ts` now exposes `listEntityUsers`, `updateEntityUsers`, and `listPlatformUsers` helpers. Verified on live `:8069`: admin gets `200`, non-admin gets `403`, and `/api/user` reflects newly linked entities after re-login so the header switcher shows them.
> - **2026-04-26 (frontend entity switcher + automatic scope propagation):** Added active-entity selection to the authenticated frontend session. `AuthContext` now tracks `selectedEntityId`/`selectedEntity`, persists it in local storage (`encoach_entity_id`), auto-validates it against the logged-in user’s entity memberships, and resets it on logout. `AdminLmsLayout` now exposes an entity switcher in the header (for users with entities) and refreshes route data after switching. `api-client` now auto-injects `entity_id` for entity-scoped LMS endpoints (`/courses`, `/students`, `/teachers`, `/batches`, `/student/my-courses`) in query params and request bodies when the caller didn’t pass one explicitly. This complements the backend guardrails so managers can intentionally switch between isolated entity LMS contexts from UI while backend remains the source of truth.
> - **2026-04-26 (entity-isolated LMS backend guardrails):** Implemented server-side entity isolation for core LMS APIs so users only see/manage records within their linked entities. Added `entity_id` ownership fields to `op.batch`, `op.student`, `op.faculty` (and kept `op.course.entity_id` in this module extension), then enforced scoped domains + access checks in `encoach_lms_api/controllers/lms_core.py` across courses/students/teachers/batches and enrollment flows. Creation now auto-defaults to the caller’s first entity when `entity_id` is omitted (non-super users), supports explicit `entity_id` with access validation, and returns **403** on cross-entity access attempts. Serializers now expose `entity_id`/`entity_name` for these LMS records. Verified locally after module upgrade (`-u encoach_lms_api`): non-super user with entity `{1}` sees only entity `1` courses and gets `403` for `?entity_id=3`.
> - **2026-04-26 (course-plan material authoring + entity assignment):** Upgraded AI course-plan delivery UX from raw JSON to an editable, book-style material experience. Added `PATCH /api/ai/course-plan/material/<id>` to edit generated material title/summary/body text, plus new metadata fields on `encoach.course.plan.material`: `share_date` (editable) and `is_static` (preserved on regenerate). Week regeneration now keeps static rows (`generate_week_materials` only replaces non-static materials). Added multi-entity assignment support with new assignment mode `entities` (`entity_ids`), including API create/list payloads and student visibility expansion via entity membership. Admin detail now supports student-preview mode, per-skill color badges + filtering, simple content editing (not code view), share-date/static controls, and entity picker in assignment dialog. Student detail now renders the same book-style material view with per-skill filters and authenticated media preview URLs. Module upgraded locally with `-u encoach_ai_course`; API smoke verified: material patch + entity assignment both pass.
> - **2026-04-25 (full demo seed + 8-role E2E):** Filled every product `user_type` with believable demo data and ran end-to-end smoke + mutation tests across all eight roles. New idempotent seeders (`seed_full_demo.py`, `reset_demo_passwords.py`) add the 5 missing user types (`approver`, `corporate`, `mastercorporate`, `agent`, `developer`), an active 2-stage exam-approval workflow with one pending request, and a full **GE1-aligned B1 course plan** modelled on the UTAS *General English 1 Fall AY25-26* outline (12 weeks, 6 detailed week-1 materials covering reading / writing / listening / speaking / grammar / vocabulary). New `e2e_full_scenario.py` exercises the API surface for each role (**46/46 PASS, 0 fail** across admin/teacher/approver/student/corporate/mastercorporate/agent/developer) and `e2e_approval_chain.py` walks the full mutation path: approver approves stage 1 → admin approves stage 2 → linked exam auto-published. Live LangGraph round-trips verified during the run (writing_grader 3.3 s, lms_tutor ReAct with 2 real tool calls 13 s). Full QA write-up in `docs/ENCOACH_FULL_DEMO_QA_REPORT.md`. See §23.
> - **2026-04-25 (LangGraph as core AI runtime):** Made LangGraph the backbone for every AI feature on the platform — course planning, exam/exercise generation, LMS tutor, writing/speaking grading. New `encoach.ai.agent` + `encoach.ai.tool` Odoo models (M2M tool binding, graph type, model, temperature, fallback model, max revisions, quality checks, system prompt, prompt key, response format). New `services/agent_runtime.py` compiles each agent into a `StateGraph` with four topologies (`simple`, `plan_review_revise`, `rag`, `react`) and `services/agent_tools.py` ships an 11-tool registry wrapping existing services (vector search, rubric/outcomes/student fetch, CEFR/AI-detect/content-gate, course-plan persistence, writing/speaking grading). 7 default agents seeded via `data/agents_defaults.xml`. New `/api/ai/agents*` controller (list/get/update/test, list-tools, toggle-tool). The page at `/admin/ai/prompts` is now a tabbed **Agents | Tools | Prompts** console with a config dialog (graph type, model, temperature, fallback, max revisions, quality checks, tool toggles) and a built-in Test Runner that shows output + tool trace + retrieval hits + revisions + quality issues. EN + AR (RTL) translations for every new string. The `CoursePlanPipeline` now routes through `AgentRuntime` when `encoach_ai.use_langgraph_runtime` is on. See §22.
> - **2026-04-19 (reports section):** Built the Reports section end-to-end — the three pages `/admin/student-performance`, `/admin/stats-corporate`, `/admin/record` (previously pure hardcoded-array mocks) are now wired to real aggregated data from `encoach.student.attempt`. New `/api/reports/{student-performance,stats-corporate,record,filters}` controller (`encoach_lms_api/controllers/reports.py`) does the rollups: per-student band averages + CEFR, per-module corporate charts, trend / distribution / entity comparison, and per-user attempt history with search / level / entity / period filters and CSV export. New `seed_reports.py` completes in-progress attempts and backfills six months of historical attempts so the trend chart and KPI cards are meaningful. 25/25 API smoke passing (`test_reports_flows.py`), 24/24 Configuration + 29/29 Support + 26/26 Training regressions still green, all three pages verified live in-browser with 28 real attempts showing across 4 tabs. See §20.
@@ -399,6 +403,8 @@ Stored in macOS Keychain for `git.albousalh.com`:
| Method | Route | Description |
|--------|-------|-------------|
| GET | `/api/entities` | List entities |
| GET | `/api/entities/<entity_id>/users` | List users assigned to the entity (**admin only**) |
| PATCH/PUT | `/api/entities/<entity_id>/users` | Replace assigned entity users with `user_ids` (**admin only**) |
### LMS Core (`encoach_lms_api` — `lms_core.py`)
| Method | Route | Description |