EnCoach Odoo 19 custom modules

Full backend implementation with custom Odoo modules:
- encoach_api: Core API, user management, JWT auth
- encoach_exam: Exam generation (reading, writing, listening, speaking)
- encoach_evaluate: AI-powered evaluation (writing, speaking)
- encoach_training: Training tips and walkthrough
- encoach_storage: File storage management
- encoach_payment: Stripe, PayPal, Paymob integration
- encoach_mail: Email notifications

Made-with: Cursor

.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.venv/
+env/
+venv/
+*.log
+.DS_Store
+Archive/

DEVELOPER_FEEDBACK.md

@@ -0,0 +1,249 @@
+# EnCoach Odoo 19 -- Developer Feedback
+
+**Date:** March 11, 2026
+**Status:** ALL ITEMS RESOLVED (March 13, 2026)
+**Reference:** ODOO_MIGRATION_SRS_v2.md
+
+---
+
+## Overall Assessment
+
+The delivery covers approximately **85% of the SRS v2 requirements**. All 15 custom modules are present, the core AI/ML services are well-implemented, data models match the specification, and 67-72 API endpoints are wired up with proper JWT authentication and security groups. The code quality is solid -- clean structure, proper error handling, and good separation of concerns.
+
+The items below still need to be implemented to reach full SRS compliance.
+
+---
+
+## 1. Payment Integration (Critical -- Not Implemented)
+
+**SRS Reference:** Section 7
+
+All three payment services are currently stubs that return `"not yet implemented"`. The SRS requires full integration with:
+
+### 1.1 Stripe
+
+**Files:** `encoach_subscription/services/stripe_service.py`
+
+Required functionality:
+- Install and use the `stripe` Python SDK
+- `create_checkout_session()` -- Create a Stripe Checkout Session using `stripe.checkout.Session.create()` with:
+  - `line_items` from the selected `encoach.package`
+  - `success_url` and `cancel_url` from the request
+  - `client_reference_id` = user ID
+  - `customer_email` = user email
+  - Apply discount if `discount_code` is provided (validate against `encoach.discount`)
+- Return `{ "sessionId": "cs_...", "url": "https://checkout.stripe.com/..." }`
+- **Webhook endpoint** (`POST /api/stripe/webhook`):
+  - Verify signature using `stripe.Webhook.construct_event()` with `STRIPE_WEBHOOK_SECRET`
+  - Handle `checkout.session.completed` event:
+    - Find user by `client_reference_id`
+    - Extend `subscription_expiration` by the package's `duration_days`
+    - Create `encoach.subscription.payment` record
+    - For corporate users, propagate subscription to entity members
+
+### 1.2 PayPal
+
+**Files:** `encoach_subscription/services/paypal_service.py`
+
+Required functionality:
+- Use PayPal REST API (`httpx` or `requests`)
+- Obtain access token from `PAYPAL_ACCESS_TOKEN_URL` using `client_id` + `client_secret`
+- `create_order()` -- Create PayPal order via `POST /v2/checkout/orders`:
+  - `intent: "CAPTURE"`
+  - `purchase_units` with amount from package (minus discount)
+  - Return `{ "orderId": "...", "approvalUrl": "https://paypal.com/..." }`
+- `capture_order()` -- Capture approved order via `POST /v2/checkout/orders/{id}/capture`:
+  - On success, extend subscription and create payment record
+  - Return `{ "ok": true }`
+
+### 1.3 Paymob
+
+**Files:** `encoach_subscription/services/paymob_service.py`
+
+Required functionality:
+- Use Paymob API (`httpx` or `requests`)
+- `create_intention()` -- Create payment intention:
+  - Authenticate with `PAYMOB_API_KEY`
+  - Create order, then payment key
+  - Return `{ "intentionId": "...", "clientSecret": "..." }`
+- `verify_transaction()` -- Verify webhook callback:
+  - Validate HMAC using `PAYMOB_SECRET`
+  - On success, extend subscription and create payment record
+- **Webhook endpoint** (`POST /api/paymob/webhook`):
+  - Verify transaction authenticity
+  - Update subscription on success
+
+### 1.4 Subscription Extension Logic
+
+After any successful payment (all providers), the system must:
+1. Calculate new expiration: `max(current_expiration, now()) + duration_days`
+2. Update `user.subscription_expiration`
+3. Create `encoach.subscription.payment` record with provider, amount, transaction ID
+4. For corporate users: propagate the new expiration to all entity members
+
+---
+
+## 2. Missing API Endpoints
+
+**SRS Reference:** Section 4
+
+The following endpoints are specified in the SRS but not present in the delivery:
+
+### 2.1 Exam Variants (add to `encoach_api/controllers/generation.py` or `exams.py`)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `POST /api/exam/writing/<task>/attachment` | POST | Academic writing Task 1 with image upload (multipart form with `file` + `difficulty`). Must send image to GPT-4o vision API for prompt generation. |
+| `GET /api/exam/level/` | GET | Return a pre-built level exam (no AI generation) |
+| `GET /api/exam/level/utas` | GET | Return a UTAS-format level exam |
+| `POST /api/exam/level/import/` | POST | Import level exam from uploaded file |
+| `POST /api/exam/level/custom/` | POST | Generate custom level exam from JSON specification |
+| `POST /api/exam/reading/import` | POST | Import reading exam from Word/Excel file |
+| `POST /api/exam/listening/import` | POST | Import listening exam from file |
+
+### 2.2 Entity/Role/Permission Management (new controller files needed)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `GET /api/entities` | GET | List entities (with pagination) |
+| `POST /api/entities` | POST | Create entity |
+| `PATCH /api/entities/<id>` | PATCH | Update entity |
+| `DELETE /api/entities/<id>` | DELETE | Delete entity |
+| `GET /api/roles` | GET | List roles (filter by entityID) |
+| `POST /api/roles` | POST | Create role |
+| `PATCH /api/roles/<id>` | PATCH | Update role |
+| `DELETE /api/roles/<id>` | DELETE | Delete role |
+| `GET /api/permissions` | GET | List permissions |
+
+### 2.3 Other Missing Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `GET /api/discounts` | GET | List discount codes |
+| `POST /api/discounts` | POST | Create discount code |
+| `PATCH /api/discounts/<id>` | PATCH | Update discount code |
+| `DELETE /api/discounts/<id>` | DELETE | Delete discount code |
+| `GET /api/approval-workflows` | GET | List approval workflows |
+| `POST /api/approval-workflows` | POST | Create approval workflow |
+| `PATCH /api/approval-workflows/<id>` | PATCH | Update approval workflow |
+| `DELETE /api/approval-workflows/<id>` | DELETE | Delete approval workflow |
+
+---
+
+## 3. Evaluation Status Endpoint Path
+
+**SRS Reference:** Section 4.2
+
+**Current:** `GET /api/evaluate/status?sessionId=...&exerciseId=...` (query params)
+**SRS specifies:** `GET /api/evaluate/<sessionId>/<exerciseId>` (path params)
+
+The frontend SRS document (`ODOO_MIGRATION_FRONTEND_SRS.md`) references the path-param version. Please either:
+- (A) Change the endpoint to use path params to match the SRS, OR
+- (B) Confirm that query params are intentional so we can update the frontend SRS
+
+---
+
+## 4. Record-Level Security Rules (`ir.rule`)
+
+**SRS Reference:** Section 5
+
+The delivery has model-level ACL rules (`ir.model.access.csv`) for each module, which is good. However, record-level security rules (`ir.rule`) are also needed to ensure:
+
+- **Students** can only read/write their own records (sessions, stats, evaluations, training, tickets)
+- **Teachers** can see records for students in their groups/assignments
+- **Corporate** users can see records within their entity
+- **Admin/Developer** users have unrestricted access
+
+Example rules needed (add to each module's `security/` directory):
+
+```xml
+<!-- encoach_stats/security/rules.xml -->
+<record id="rule_stat_student_own" model="ir.rule">
+    <field name="name">Students see own stats</field>
+    <field name="model_id" ref="model_encoach_stat"/>
+    <field name="groups" eval="[(4, ref('encoach_core.group_encoach_student'))]"/>
+    <field name="domain_force">[('user_id', '=', user.id)]</field>
+</record>
+```
+
+Models that need record rules:
+- `encoach.session` -- students see own sessions only
+- `encoach.stat` -- students see own stats only
+- `encoach.evaluation` -- students see own evaluations only
+- `encoach.training` -- students see own training only
+- `encoach.ticket` -- students see own tickets, admins see all
+- `encoach.assignment` -- students see assignments they're assigned to
+- `encoach.exam` -- filtered by access field (public/private/entity)
+
+---
+
+## 5. Whisper Scaling
+
+**SRS Reference:** Section 6.5
+
+**Current:** Single lazy-loaded Whisper model instance in `whisper_service.py`
+**SRS specifies:** 4 model instances with `ThreadPoolExecutor(max_workers=4)` for parallel transcription
+
+Update `encoach_ai_media/services/whisper_service.py` to:
+1. Load the configurable number of model instances (from `encoach.whisper_workers` system parameter, default 4)
+2. Use `concurrent.futures.ThreadPoolExecutor` to process transcription requests in parallel
+3. Round-robin or queue-based assignment of requests to model instances
+
+This is important for production performance when multiple students submit speaking exams simultaneously.
+
+---
+
+## 6. FAISS Index Type
+
+**SRS Reference:** Section 6.8
+
+**Current:** `faiss.IndexFlatIP` (inner product)
+**SRS specifies:** `faiss.IndexFlatL2` (L2/Euclidean distance)
+
+The current implementation normalizes vectors and uses inner product, which effectively gives cosine similarity. This works correctly, but it's a deviation from the SRS. If the original `ielts-be` training data was built with L2 distance, the results may differ slightly. Please verify which index type the original system used and align accordingly.
+
+---
+
+## 7. Payment Webhook Endpoints
+
+**SRS Reference:** Section 7
+
+In addition to the payment service implementations (Item 1 above), the following webhook controller routes need to be added to `encoach_api/controllers/subscriptions.py`:
+
+```python
+@http.route('/api/stripe/webhook', type='http', auth='public', methods=['POST'], csrf=False, cors='*')
+def stripe_webhook(self, **kwargs):
+    """Handle Stripe webhook events (checkout.session.completed, etc.)."""
+    ...
+
+@http.route('/api/paymob/webhook', type='http', auth='public', methods=['POST'], csrf=False, cors='*')
+def paymob_webhook(self, **kwargs):
+    """Handle Paymob transaction callbacks."""
+    ...
+```
+
+These must be `auth='public'` (no JWT) since they're called by external services.
+
+---
+
+## Summary of Action Items
+
+| # | Item | Priority | Status |
+|---|------|----------|--------|
+| 1 | Payment integration (Stripe/PayPal/Paymob) | **Critical** | RESOLVED |
+| 2 | Missing API endpoints (~20 endpoints) | **High** | RESOLVED |
+| 3 | Evaluation status endpoint path alignment | **Medium** | RESOLVED |
+| 4 | `ir.rule` record-level security rules | **High** | RESOLVED |
+| 5 | Whisper multi-instance scaling | **Medium** | RESOLVED |
+| 6 | FAISS index type verification | **Low** | RESOLVED |
+| 7 | Payment webhook endpoints | **Critical** | RESOLVED |
+
+---
+
+## Changes Already Applied
+
+The following small fixes have been applied directly to the codebase:
+
+1. **`encoach_ai_media/__manifest__.py`** -- Added missing `external_dependencies`: `numpy`, `openai-whisper`, `librosa`, `soundfile`, `httpx`
+2. **`encoach_training/__manifest__.py`** -- Added missing `external_dependencies`: `numpy`, `faiss-cpu`, `sentence-transformers`
+3. **`requirements.txt`** -- Created at project root with all Python dependencies and versions from SRS Section 6.10

ENCOACH_AI_KEYS.md

@@ -0,0 +1,158 @@
+# EnCoach AI & Service Keys Configuration
+
+All API keys are stored as Odoo **System Parameters** (`ir.config_parameter`).
+
+---
+
+## How to Set Keys
+
+### Via Odoo UI
+
+1. Login as `admin` / `admin` at http://127.0.0.1:8069/web
+2. Navigate to **Settings > Technical > Parameters > System Parameters**
+3. Search for `encoach.` to filter all EnCoach keys
+4. Click a parameter and paste your key into the **Value** field
+5. Save — changes take effect immediately (no restart needed)
+
+### Via Terminal
+
+```bash
+cd /Users/yamenahmad/projects2026/odoo/odoo19/odoo
+
+../.conda-envs/odoo19/bin/python odoo-bin shell -c ../odoo.conf -d encoach <<'EOF'
+params = env['ir.config_parameter'].sudo()
+params.set_param('encoach.openai_api_key', 'sk-your-key-here')
+params.set_param('encoach.aws_access_key_id', 'AKIA...')
+params.set_param('encoach.aws_secret_access_key', 'your-aws-secret')
+params.set_param('encoach.elai_token', 'your-elai-token')
+params.set_param('encoach.gptzero_api_key', 'your-gptzero-key')
+params.set_param('encoach.jwt_secret', 'a-strong-random-secret-256-bits')
+env.cr.commit()
+print("All keys set.")
+EOF
+```
+
+---
+
+## Key Reference
+
+### Core
+
+| Parameter | Description | Required | Where to Get |
+|-----------|-------------|----------|-------------|
+| `encoach.jwt_secret` | JWT signing secret for API authentication | Yes | Generate a random 256-bit string |
+| `encoach.jwt_expiry_hours` | JWT token expiry in hours (default: 72) | No | Set any integer |
+
+### OpenAI (GPT-4o, Whisper)
+
+Used by: Exam generation, writing/speaking evaluation, grading, training tips.
+
+| Parameter | Description | Required | Where to Get |
+|-----------|-------------|----------|-------------|
+| `encoach.openai_api_key` | OpenAI API key | Yes | https://platform.openai.com/api-keys |
+
+**Models used:**
+- `gpt-4o` — Exam generation, evaluation, grading, training
+- `whisper-1` — Audio transcription (speaking evaluation)
+
+### AWS (Polly TTS)
+
+Used by: Listening exam audio generation, instruction audio.
+
+| Parameter | Description | Required | Where to Get |
+|-----------|-------------|----------|-------------|
+| `encoach.aws_access_key_id` | AWS IAM Access Key ID | Yes | https://console.aws.amazon.com/iam/ |
+| `encoach.aws_secret_access_key` | AWS IAM Secret Access Key | Yes | Same as above |
+
+**AWS services used:**
+- **Amazon Polly** — Text-to-speech for listening exam audio
+- **Region:** Configured in `polly_service.py` (default: `us-east-1`)
+
+**Required IAM permissions:**
+```json
+{
+  "Effect": "Allow",
+  "Action": ["polly:SynthesizeSpeech"],
+  "Resource": "*"
+}
+```
+
+### ELAI.io (Avatar Videos)
+
+Used by: Speaking exam video generation with AI avatars.
+
+| Parameter | Description | Required | Where to Get |
+|-----------|-------------|----------|-------------|
+| `encoach.elai_token` | ELAI API token | For speaking videos | https://elai.io/api |
+
+### GPTZero (Plagiarism Detection)
+
+Used by: AI-generated content detection in writing submissions.
+
+| Parameter | Description | Required | Where to Get |
+|-----------|-------------|----------|-------------|
+| `encoach.gptzero_api_key` | GPTZero API key | Optional | https://gptzero.me/api |
+
+### Stripe (Payments)
+
+Used by: Subscription checkout.
+
+| Parameter | Description | Required | Where to Get |
+|-----------|-------------|----------|-------------|
+| `encoach.stripe_secret_key` | Stripe secret key (`sk_test_...` or `sk_live_...`) | For Stripe payments | https://dashboard.stripe.com/apikeys |
+| `encoach.stripe_webhook_secret` | Stripe webhook signing secret (`whsec_...`) | For webhooks | https://dashboard.stripe.com/webhooks |
+
+### PayPal (Payments)
+
+Used by: Subscription checkout.
+
+| Parameter | Description | Required | Where to Get |
+|-----------|-------------|----------|-------------|
+| `encoach.paypal_client_id` | PayPal REST API Client ID | For PayPal payments | https://developer.paypal.com/dashboard/applications |
+| `encoach.paypal_client_secret` | PayPal REST API Client Secret | For PayPal payments | Same as above |
+
+### Paymob (Payments)
+
+Used by: Subscription checkout (Middle East region).
+
+| Parameter | Description | Required | Where to Get |
+|-----------|-------------|----------|-------------|
+| `encoach.paymob_api_key` | Paymob API key | For Paymob payments | https://accept.paymob.com/portal2/en/settings |
+
+---
+
+## Which Keys Are Needed for What
+
+| Feature | Keys Required |
+|---------|--------------|
+| User registration & login | `jwt_secret` |
+| Generate reading/listening/writing/speaking exams | `openai_api_key` |
+| Grade writing answers | `openai_api_key` |
+| Grade speaking answers | `openai_api_key` |
+| Generate listening audio (MP3) | `aws_access_key_id` + `aws_secret_access_key` |
+| Transcribe audio (Whisper) | `openai_api_key` |
+| Generate speaking avatar video | `elai_token` |
+| Detect AI-generated content | `gptzero_api_key` |
+| Personalised training tips | `openai_api_key` |
+| Stripe payments | `stripe_secret_key` + `stripe_webhook_secret` |
+| PayPal payments | `paypal_client_id` + `paypal_client_secret` |
+| Paymob payments | `paymob_api_key` |
+
+---
+
+## Minimum Setup (to test AI features)
+
+For basic AI testing, you only need **one key**:
+
+```bash
+cd /Users/yamenahmad/projects2026/odoo/odoo19/odoo
+../.conda-envs/odoo19/bin/python odoo-bin shell -c ../odoo.conf -d encoach <<'EOF'
+env['ir.config_parameter'].sudo().set_param('encoach.openai_api_key', 'sk-your-openai-key')
+env.cr.commit()
+print("OpenAI key set.")
+EOF
+```
+
+This enables: exam generation, writing evaluation, speaking evaluation (text grading), short-answer grading, and training tips.
+
+Add AWS keys later for listening audio, ELAI for avatar videos, and payment keys when ready for subscriptions.

ENCOACH_SUMMARY.md

@@ -0,0 +1,345 @@
+# EnCoach Odoo 19 – Project Summary
+
+## Overview
+
+The **EnCoach IELTS platform** (originally Node.js / MongoDB / Firebase) has been migrated into **15 custom Odoo 19 modules** that replicate all business logic inside Odoo Community Edition.
+
+---
+
+## Module Map
+
+| Module | Purpose |
+|--------|---------|
+| `encoach_core` | Users, entities (orgs), roles, permissions, registration codes, invites |
+| `encoach_exam` | Exam builder with parts/exercises/questions (JSON), approval workflows |
+| `encoach_classroom` | Student groups / classrooms |
+| `encoach_assignment` | Assignments with start / release / archive lifecycle |
+| `encoach_stats` | Exam sessions and score statistics |
+| `encoach_evaluation` | AI-powered writing & speaking evaluation jobs |
+| `encoach_ai` | Core AI services (OpenAI, prompt management) |
+| `encoach_ai_grading` | Multi-answer grading, GPTZero plagiarism checks |
+| `encoach_ai_generation` | AI exam content generation (reading / writing / speaking / listening) |
+| `encoach_ai_media` | AWS Polly audio, ELAI video avatars, Whisper transcription |
+| `encoach_training` | Personalised training plans, tips (FAISS semantic search), walkthroughs |
+| `encoach_subscription` | Packages, payments (Stripe / PayPal / Paymob), discount codes |
+| `encoach_registration` | Registration code management service |
+| `encoach_ticket` | Support ticket system |
+| `encoach_api` | REST API layer (67 endpoints) with JWT authentication |
+
+---
+
+## How to Run
+
+### Prerequisites
+
+- Python 3.12 (via Miniconda)
+- PostgreSQL (local, via Conda)
+
+### Start PostgreSQL
+
+```bash
+cd /Users/yamenahmad/projects2026/odoo/odoo19
+.conda-envs/odoo19/bin/pg_ctl -D pgdata -l pg.log start
+```
+
+### Start Odoo
+
+```bash
+cd /Users/yamenahmad/projects2026/odoo/odoo19/odoo
+../.conda-envs/odoo19/bin/python odoo-bin -c ../odoo.conf -d encoach
+```
+
+### Fresh Install (drop + recreate)
+
+```bash
+.conda-envs/odoo19/bin/dropdb -h localhost -U yamenahmad encoach
+.conda-envs/odoo19/bin/createdb -h localhost -U yamenahmad encoach
+
+cd odoo
+../.conda-envs/odoo19/bin/python odoo-bin -c ../odoo.conf -d encoach -i encoach_api --stop-after-init
+```
+
+After fresh install, set the admin password:
+
+```bash
+cd odoo
+../.conda-envs/odoo19/bin/python odoo-bin shell -c ../odoo.conf -d encoach <<'EOF'
+user = env['res.users'].browse(2)
+user.password = 'admin'
+env.cr.commit()
+EOF
+```
+
+---
+
+## Access the System
+
+### Odoo Backend (Admin UI)
+
+| | |
+|--|--|
+| **URL** | http://127.0.0.1:8069/web |
+| **Login** | `admin` |
+| **Password** | `admin` |
+
+The **EnCoach** top-level menu contains: Users & Entities, Exams, Classroom, AI & Grading, Training, Subscriptions, Support, Configuration.
+
+### REST API (for the frontend)
+
+| | |
+|--|--|
+| **Base URL** | http://127.0.0.1:8069 |
+| **Auth** | JWT Bearer token (obtained via `/api/login`) |
+| **Format** | JSON request / response |
+
+---
+
+## API Collection (67 Endpoints)
+
+### Auth (4)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/register` | Register new user |
+| POST | `/api/login` | Login – returns JWT token |
+| POST | `/api/logout` | Logout |
+| POST | `/api/reset` | Reset password |
+| POST | `/api/reset/sendVerification` | Send reset verification |
+
+### Users (6)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/user` | Get current user (from JWT) |
+| POST / PATCH | `/api/users/update` | Update profile |
+| GET | `/api/users/list` | List / search users |
+| GET | `/api/users/<id>` | Get user by ID |
+| POST | `/api/users/controller` | User admin actions |
+| GET | `/api/users/balance` | Get user balance |
+
+### Registration Codes (3)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/code/<code>` | Validate registration code |
+| POST | `/api/batch_users` | Batch-create users |
+| POST | `/api/make_user` | Create single user |
+
+### Exams (7)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/exam` | List exams (filter by `?module=`) |
+| POST | `/api/exam/<module>` | Create exam |
+| GET | `/api/exam/<module>/<id>` | Get exam |
+| PATCH | `/api/exam/<module>/<id>` | Update exam |
+| DELETE | `/api/exam/<module>/<id>` | Delete exam |
+| POST | `/api/exam/<module>/import/` | Import exam from file |
+| GET | `/api/exam/avatars` | List exam avatars |
+
+### Classrooms (4)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/groups` | List groups |
+| POST | `/api/groups` | Create group |
+| PATCH | `/api/groups/<id>` | Update group |
+| DELETE | `/api/groups/<id>` | Delete group |
+
+### Assignments (8)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/assignments` | List assignments |
+| POST | `/api/assignments` | Create assignment |
+| PATCH | `/api/assignments/<id>` | Update assignment |
+| DELETE | `/api/assignments/<id>` | Delete assignment |
+| POST | `/api/assignments/<id>/start` | Start assignment |
+| POST | `/api/assignments/<id>/release` | Release results |
+| POST | `/api/assignments/<id>/archive` | Archive |
+| POST | `/api/assignments/<id>/unarchive` | Unarchive |
+
+### Sessions & Stats (4)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/sessions` | Save exam session |
+| DELETE | `/api/sessions/<id>` | Delete session |
+| POST | `/api/stats` | Save statistics |
+| GET | `/api/stats/<id>` | Get stat by ID |
+| POST | `/api/statistical` | Query / aggregate stats |
+
+### AI Evaluation (4)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/evaluate/writing` | Evaluate writing answer |
+| POST | `/api/evaluate/speaking` | Evaluate speaking (audio) |
+| POST | `/api/evaluate/interactiveSpeaking` | Evaluate interactive speaking |
+| GET | `/api/evaluate/status` | Poll evaluation job status |
+
+### AI Generation (7)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/exam/reading/<passage>` | Generate reading passage |
+| POST | `/api/exam/reading/` | Generate reading exercises |
+| GET | `/api/exam/listening/<section>` | Generate listening dialog |
+| POST | `/api/exam/listening/` | Generate listening exercises |
+| GET | `/api/exam/writing/<task>` | Generate writing task |
+| GET | `/api/exam/speaking/<task>` | Generate speaking task |
+| POST | `/api/exam/level/` | Generate level-test exercises |
+
+### AI Media (7)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/exam/listening/media` | Generate listening MP3 (AWS Polly) |
+| POST | `/api/exam/listening/transcribe` | Transcribe audio to dialog |
+| POST | `/api/exam/listening/instructions` | Generate instructions MP3 |
+| POST | `/api/exam/speaking/media` | Start AI avatar video generation |
+| GET | `/api/exam/speaking/media/<vid>` | Poll video generation status |
+| GET | `/api/exam/speaking/avatars` | List speaking avatars |
+| POST | `/api/transcribe` | Transcribe audio file (Whisper) |
+
+### Training (4)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/training` | Generate personalised training plan |
+| GET | `/api/training/<id>` | Get training by ID |
+| POST | `/api/training/tips` | Get contextual tips |
+| GET | `/api/training/walkthrough` | Get walkthrough |
+
+### Subscriptions & Payments (5)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/packages` | List subscription packages |
+| POST | `/api/stripe` | Create Stripe checkout session |
+| POST | `/api/paypal` | Create PayPal order |
+| POST | `/api/paypal/approve` | Capture / approve PayPal order |
+| POST | `/api/paymob` | Create PayMob payment intention |
+
+### Tickets (4)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/tickets` | List support tickets |
+| POST | `/api/tickets` | Create ticket |
+| PATCH | `/api/tickets/<id>` | Update ticket |
+| DELETE | `/api/tickets/<id>` | Delete ticket |
+
+### Storage (2)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/storage` | Upload file |
+| POST | `/api/storage/delete` | Delete file |
+
+### Grading (2)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/grading/multiple` | Grade multiple short-answer exercises |
+| POST | `/api/exam/grade/summary` | Generate grading summary |
+
+---
+
+## Quick Test
+
+```bash
+# 1. Register a user
+curl -s http://127.0.0.1:8069/api/register \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@test.com","password":"Pass1234","name":"Test User","type":"student"}'
+
+# 2. Login – get JWT token
+TOKEN=$(curl -s http://127.0.0.1:8069/api/login \
+  -H "Content-Type: application/json" \
+  -d '{"credential":"test@test.com","password":"Pass1234"}' \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")
+
+# 3. Get current user (authenticated)
+curl -s http://127.0.0.1:8069/api/user \
+  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
+
+# 4. List exams
+curl -s "http://127.0.0.1:8069/api/exam?module=reading" \
+  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
+
+# 5. Create a ticket
+curl -s http://127.0.0.1:8069/api/tickets \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"subject":"Test ticket","description":"Just testing","type":"feedback"}'
+
+# 6. List packages
+curl -s http://127.0.0.1:8069/api/packages \
+  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
+```
+
+---
+
+## File Structure
+
+```
+addons_extra/
+├── encoach_core/
+│   ├── __manifest__.py
+│   ├── models/          # entity, role, permission, code, invite, res_users, user_entity_rel
+│   ├── security/        # security.xml (groups), ir.model.access.csv
+│   ├── data/            # constants.xml, assign_admin_group.xml
+│   ├── views/           # menu.xml + views for every model
+│   └── scripts/         # migrate_mongodb.py, migrate_firebase_auth.py, rebuild_faiss.py, import_avatars.py
+├── encoach_exam/
+│   ├── models/          # exam.py, approval_workflow.py
+│   └── views/
+├── encoach_classroom/
+│   ├── models/          # group.py
+│   └── views/
+├── encoach_assignment/
+│   ├── models/          # assignment.py
+│   └── views/
+├── encoach_stats/
+│   ├── models/          # session.py, stat.py
+│   └── views/
+├── encoach_evaluation/
+│   ├── models/          # evaluation.py, ai_job.py
+│   └── views/
+├── encoach_ai/
+│   └── services/        # openai_service.py, prompt_service.py
+├── encoach_ai_grading/
+│   └── services/        # grading_service.py, gptzero_service.py
+├── encoach_ai_generation/
+│   └── services/        # reading, listening, writing, speaking, level generators
+├── encoach_ai_media/
+│   ├── models/          # elai_avatar.py
+│   ├── services/        # polly_service.py, elai_service.py, whisper_service.py
+│   └── views/
+├── encoach_training/
+│   ├── models/          # training.py, tip.py, walkthrough.py
+│   ├── services/        # training_service.py, faiss_service.py
+│   └── views/
+├── encoach_subscription/
+│   ├── models/          # package.py, payment.py, discount.py
+│   ├── services/        # stripe_service.py, paypal_service.py, paymob_service.py
+│   └── views/
+├── encoach_registration/
+│   └── services/        # code_service.py
+├── encoach_ticket/
+│   ├── models/          # ticket.py
+│   └── views/
+└── encoach_api/
+    └── controllers/     # 16 controller files (auth, users, exams, classrooms, etc.)
+```
+
+---
+
+## Key Technical Decisions
+
+- **JSON fields** (`fields.Json`) used extensively for complex nested data (exam parts, scores, solutions) to match existing MongoDB document shapes.
+- **JWT authentication** via `PyJWT` for stateless API auth, stored secret in `ir.config_parameter`.
+- **Odoo 19 changes**: `group_ids` (not `groups_id`), no `category_id` on `res.groups`, `models.Constraint` instead of `_sql_constraints`.
+- **Security**: Each model has ACL rules for Student (read-only), Teacher (read/write), Admin (full CRUD), and `base.group_system` (Odoo admin full CRUD).
+- **Admin user** is automatically added to the EnCoach Developer group (which implies Admin and Teacher) on install.

README.md

@@ -0,0 +1,5 @@
+# Extra / custom addons
+
+Put your custom or third-party Odoo modules here (each as a subfolder with `__manifest__.py`).
+
+This path is loaded first, so your modules override Community modules with the same name.

encoach_ai/__init__.py

@@ -0,0 +1,2 @@
+from . import models
+from . import services

encoach_ai/__manifest__.py

@@ -0,0 +1,16 @@
+{
+    "name": "EnCoach AI",
+    "version": "19.0.1.0.0",
+    "category": "Education",
+    "summary": "Core AI services for the EnCoach IELTS platform",
+    "description": "OpenAI integration, constants, blacklist validation, token counting.",
+    "depends": ["encoach_core"],
+    "data": [
+        "security/ir.model.access.csv",
+    ],
+    "installable": True,
+    "license": "LGPL-3",
+    "external_dependencies": {
+        "python": ["openai", "tiktoken", "httpx", "tenacity", "numpy"],
+    },
+}

encoach_ai/models/__init__.py

@@ -0,0 +1 @@
+from . import constants

encoach_ai/models/constants.py

@@ -0,0 +1,59 @@
+BLACKLISTED_WORDS = [
+    "alcohol", "atheism", "beer", "bible", "blasphemy",
+    "buddha", "buddhism", "cannabis", "casino", "christ",
+    "christianity", "church", "cocaine", "communist", "condom",
+    "corruption", "crucifixion", "cult", "drug", "drugs",
+    "erotic", "extremism", "gambling", "gay", "god",
+    "gods", "gospel", "haram", "heresy", "heroin",
+    "hindu", "hinduism", "homosexual", "idol", "infidel",
+    "islam", "islamic", "israeli", "jesus", "jew",
+    "jewish", "jihad", "judaism", "lesbian", "liquor",
+    "marijuana", "mosque", "muhammad", "muslim", "naked",
+    "nazi", "nude", "pagan", "pig", "pork",
+    "porn", "pornography", "prayer", "priest", "prophet",
+    "prostitution", "quran", "rabbi", "rape", "religion",
+    "religious", "satan", "sex", "sexual", "sharia",
+    "shinto", "sikh", "strip", "suicide", "synagogue",
+    "temple", "terrorism", "terrorist", "torah", "vodka",
+    "whiskey", "wine", "worship", "zionism",
+]
+
+TOPICS = [
+    "Technology", "Education", "Health", "Environment", "Travel",
+    "Food and Nutrition", "Sports", "Music", "Art", "Science",
+    "History", "Geography", "Business", "Economy", "Media",
+    "Communication", "Fashion", "Architecture", "Transportation", "Energy",
+    "Water Resources", "Agriculture", "Space Exploration", "Wildlife",
+    "Climate Change", "Urbanization", "Rural Life", "Population Growth",
+    "Immigration", "Cultural Diversity", "Globalization", "Tourism",
+    "Employment", "Workplace Culture", "Leadership", "Innovation",
+    "Artificial Intelligence", "Social Media", "Advertising", "Cinema",
+    "Literature", "Languages", "Volunteering", "Charity",
+    "Mental Health", "Fitness", "Aging Population", "Childhood Development",
+    "Higher Education", "Online Learning", "Public Libraries",
+    "Museums", "Public Transport", "Cycling", "Renewable Energy",
+    "Recycling", "Waste Management", "Deforestation", "Ocean Conservation",
+    "Animal Rights", "Genetic Engineering", "Robotics", "Cybersecurity",
+    "Privacy", "Freedom of Speech", "Democracy", "Law Enforcement",
+    "Crime Prevention", "Housing", "Homelessness", "Poverty",
+    "Income Inequality", "Consumer Culture", "Minimalism", "Traditions",
+    "Festivals", "Cooking", "Gardening", "Photography",
+    "Podcasts", "Board Games", "Pet Ownership", "Astronomy",
+    "Archaeology", "Philosophy", "Psychology", "Sociology",
+    "Ecology", "Marine Biology", "Meteorology", "Geology",
+    "Time Management", "Stress Management", "Work-Life Balance",
+]
+
+CEFR_LEVELS = ["A1", "A2", "B1", "B2", "C1", "C2"]
+
+GPT_MODELS = {
+    "grading": "gpt-4o",
+    "generation": "gpt-4o",
+    "secondary": "gpt-3.5-turbo",
+}
+
+TEMPERATURE = {
+    "grading": 0.1,
+    "generation": 0.7,
+    "tips": 0.2,
+}

encoach_ai/security/ir.model.access.csv

@@ -0,0 +1 @@
+id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink

encoach_ai/services/__init__.py

@@ -0,0 +1 @@
+from . import openai_service

encoach_ai/services/openai_service.py

@@ -0,0 +1,103 @@
+import json
+import logging
+
+import tiktoken
+from openai import OpenAI
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+from ..models.constants import BLACKLISTED_WORDS
+
+_logger = logging.getLogger(__name__)
+
+TOKEN_RESERVE = 300
+MODEL_TOKEN_LIMIT = 4097
+
+
+class EncoachOpenAIService:
+
+    def __init__(self, env):
+        self.env = env
+        api_key = (
+            env["ir.config_parameter"]
+            .sudo()
+            .get_param("encoach.openai_api_key", "")
+        )
+        if not api_key:
+            _logger.warning("OpenAI API key not configured (encoach.openai_api_key)")
+        self.client = OpenAI(api_key=api_key)
+
+    def prediction(
+        self,
+        model,
+        messages,
+        temperature=0.7,
+        response_format=None,
+        fields_to_check=None,
+        check_blacklisted=True,
+        max_retries=2,
+    ):
+        """Call OpenAI chat completion with validation and blacklist filtering.
+
+        Returns parsed JSON dict on success or None on failure.
+        """
+        if response_format is None:
+            response_format = {"type": "json_object"}
+
+        input_tokens = self._count_tokens(
+            " ".join(m.get("content", "") for m in messages if isinstance(m.get("content"), str)),
+            model,
+        )
+        max_tokens = max(MODEL_TOKEN_LIMIT - input_tokens - TOKEN_RESERVE, 256)
+
+        attempt = 0
+        while attempt <= max_retries:
+            try:
+                resp = self.client.chat.completions.create(
+                    model=model,
+                    messages=messages,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                    response_format=response_format,
+                )
+                content = resp.choices[0].message.content
+                data = json.loads(content)
+
+                if check_blacklisted:
+                    text_to_check = content
+                    if fields_to_check and isinstance(data, dict):
+                        text_to_check = " ".join(
+                            str(data.get(f, "")) for f in fields_to_check
+                        )
+                    if self._check_blacklisted(text_to_check):
+                        _logger.info(
+                            "Blacklisted content detected (attempt %d/%d)",
+                            attempt + 1,
+                            max_retries + 1,
+                        )
+                        attempt += 1
+                        continue
+
+                return data
+
+            except json.JSONDecodeError:
+                _logger.warning("Invalid JSON from OpenAI (attempt %d)", attempt + 1)
+                attempt += 1
+            except Exception:
+                _logger.exception("OpenAI API error (attempt %d)", attempt + 1)
+                attempt += 1
+
+        _logger.error("OpenAI prediction failed after %d attempts", max_retries + 1)
+        return None
+
+    @staticmethod
+    def _check_blacklisted(text):
+        lower = text.lower()
+        return any(word in lower for word in BLACKLISTED_WORDS)
+
+    @staticmethod
+    def _count_tokens(text, model="gpt-4o"):
+        try:
+            encoding = tiktoken.encoding_for_model(model)
+        except KeyError:
+            encoding = tiktoken.get_encoding("cl100k_base")
+        return len(encoding.encode(text))

encoach_ai_generation/__init__.py

@@ -0,0 +1 @@
+from . import services

encoach_ai_generation/__manifest__.py

@@ -0,0 +1,13 @@
+{
+    "name": "EnCoach AI Generation",
+    "version": "19.0.1.0.0",
+    "category": "Education",
+    "summary": "AI-powered IELTS exam content generation",
+    "description": "Reading passages, listening dialogs, writing/speaking tasks, level exercises.",
+    "depends": ["encoach_ai", "encoach_exam"],
+    "data": [
+        "security/ir.model.access.csv",
+    ],
+    "installable": True,
+    "license": "LGPL-3",
+}

encoach_ai_generation/security/ir.model.access.csv

@@ -0,0 +1 @@
+id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink

encoach_ai_generation/services/__init__.py

@@ -0,0 +1 @@
+from . import generation_service

encoach_ai_generation/services/generation_service.py

@@ -0,0 +1,352 @@
+import json
+import logging
+import random
+
+from odoo.addons.encoach_ai.models.constants import (
+    CEFR_LEVELS,
+    GPT_MODELS,
+    TEMPERATURE,
+    TOPICS,
+)
+from odoo.addons.encoach_ai.services.openai_service import EncoachOpenAIService
+
+_logger = logging.getLogger(__name__)
+
+PASSAGE_DIFFICULTY = {
+    1: "fairly easy and consist of multiple paragraphs",
+    2: "fairly hard and consist of multiple paragraphs",
+    3: (
+        "very hard, present different points or theories, "
+        "cite different sources, and consist of multiple paragraphs"
+    ),
+}
+
+LISTENING_SECTION_CONFIG = {
+    1: {
+        "type": "conversation",
+        "format": '{"conversation": [{"name": "name", "gender": "gender", "text": "text"}]}',
+        "prompt": (
+            "Compose an authentic conversation between two individuals "
+            'on the topic of "{topic}". Please include random names and genders. '
+            "Include misleading discourse (dates, colors, etc.) and spelling of names. "
+            "Make sure that the generated conversation does not contain "
+            "forbidden subjects in muslim countries."
+        ),
+    },
+    2: {
+        "type": "monologue",
+        "format": '{"monologue": "monologue"}',
+        "prompt": (
+            "Generate a comprehensive monologue set in the social context "
+            'of "{topic}". Make sure that the generated monologue does not '
+            "contain forbidden subjects in muslim countries."
+        ),
+    },
+    3: {
+        "type": "conversation",
+        "format": '{"conversation": [{"name": "name", "gender": "gender", "text": "text"}]}',
+        "prompt": (
+            "Compose an authentic and elaborate conversation between "
+            'up to four individuals on the topic of "{topic}". '
+            "Please include random names and genders. Make sure that the "
+            "generated conversation does not contain forbidden subjects "
+            "in muslim countries."
+        ),
+    },
+    4: {
+        "type": "monologue",
+        "format": '{"monologue": "monologue"}',
+        "prompt": (
+            "Generate a comprehensive and complex monologue on the academic "
+            'subject of "{topic}". Make sure that the generated monologue '
+            "does not contain forbidden subjects in muslim countries."
+        ),
+    },
+}
+
+
+class EncoachGenerationService:
+
+    def __init__(self, env):
+        self.env = env
+        self.ai = EncoachOpenAIService(env)
+
+    # ------------------------------------------------------------------
+    # Reading
+    # ------------------------------------------------------------------
+
+    def generate_reading_passage(self, passage_num, topic=None, word_count=500):
+        """Generate an IELTS reading passage (passage 1, 2, or 3)."""
+        topic = topic or random.choice(TOPICS)
+        difficulty = PASSAGE_DIFFICULTY.get(passage_num, PASSAGE_DIFFICULTY[1])
+
+        system_msg = (
+            "You are a helpful assistant designed to output JSON on this format: "
+            '{"title": "title of the text", "text": "generated text"}'
+        )
+        user_msg = (
+            f"Generate an extensive text for IELTS Reading Passage {passage_num}, "
+            f'of at least {word_count} words, on the topic of "{topic}". '
+            "The passage should offer a substantial amount of information "
+            f"relevant to the chosen subject matter. It should be {difficulty}. "
+            "Make sure that the generated text does not contain forbidden "
+            "subjects in muslim countries."
+        )
+
+        return self.ai.prediction(
+            model=GPT_MODELS["generation"],
+            messages=[
+                {"role": "system", "content": system_msg},
+                {"role": "user", "content": user_msg},
+            ],
+            temperature=TEMPERATURE["generation"],
+            fields_to_check=["title", "text"],
+        )
+
+    def generate_reading_exercises(self, text, exercises_config, difficulty):
+        """Generate exercises for a reading passage.
+
+        exercises_config: list of dicts with 'type' and 'quantity' keys.
+        difficulty: CEFR level string.
+        """
+        system_msg = (
+            "You are a helpful assistant designed to output JSON. "
+            "Generate reading comprehension exercises based on the given text."
+        )
+        config_str = json.dumps(exercises_config)
+        user_msg = (
+            f"Based on the following text, generate exercises according to this "
+            f"configuration: {config_str}. Target CEFR level: {difficulty}.\n\n"
+            f'Text: "{text}"'
+        )
+
+        return self.ai.prediction(
+            model=GPT_MODELS["generation"],
+            messages=[
+                {"role": "system", "content": system_msg},
+                {"role": "user", "content": user_msg},
+            ],
+            temperature=TEMPERATURE["generation"],
+        )
+
+    # ------------------------------------------------------------------
+    # Listening
+    # ------------------------------------------------------------------
+
+    def generate_listening_dialog(self, section, topic=None, difficulty=None):
+        """Generate a listening dialog/monologue for the given section (1-4)."""
+        topic = topic or random.choice(TOPICS)
+        config = LISTENING_SECTION_CONFIG.get(section, LISTENING_SECTION_CONFIG[1])
+
+        system_msg = (
+            "You are a helpful assistant designed to output JSON on this format: "
+            + config["format"]
+        )
+        user_msg = config["prompt"].format(topic=topic)
+        if difficulty:
+            user_msg += f" Target CEFR level: {difficulty}."
+
+        return self.ai.prediction(
+            model=GPT_MODELS["generation"],
+            messages=[
+                {"role": "system", "content": system_msg},
+                {"role": "user", "content": user_msg},
+            ],
+            temperature=TEMPERATURE["generation"],
+        )
+
+    def generate_listening_exercises(self, text, exercises_config, difficulty):
+        """Generate exercises for a listening transcript."""
+        system_msg = (
+            "You are a helpful assistant designed to output JSON. "
+            "Generate listening comprehension exercises based on the given transcript."
+        )
+        config_str = json.dumps(exercises_config)
+        user_msg = (
+            f"Based on the following transcript, generate exercises according to "
+            f"this configuration: {config_str}. Target CEFR level: {difficulty}.\n\n"
+            f'Transcript: "{text}"'
+        )
+
+        return self.ai.prediction(
+            model=GPT_MODELS["generation"],
+            messages=[
+                {"role": "system", "content": system_msg},
+                {"role": "user", "content": user_msg},
+            ],
+            temperature=TEMPERATURE["generation"],
+        )
+
+    # ------------------------------------------------------------------
+    # Writing
+    # ------------------------------------------------------------------
+
+    def generate_writing_task(
+        self, task, topic=None, difficulty=None, task_type="general"
+    ):
+        """Generate a writing task prompt.
+
+        task: 1 or 2
+        task_type: 'general' or 'academic'
+        """
+        topic = topic or random.choice(TOPICS)
+        difficulty = difficulty or random.choice(CEFR_LEVELS)
+
+        system_msg = (
+            "You are a helpful assistant designed to output JSON on this format: "
+            '{"question": "the generated writing task prompt"}'
+        )
+
+        if task == 1 and task_type == "general":
+            user_msg = (
+                "Craft a prompt for an IELTS Writing Task 1 General Training "
+                "exercise that instructs the student to compose a letter based "
+                f'on the topic of "{topic}" of {difficulty} CEFR level difficulty. '
+                'The prompt should end with "In the letter you should" followed '
+                "by 3 bullet points. Make sure it does not contain forbidden "
+                "subjects in muslim countries."
+            )
+        elif task == 2:
+            user_msg = (
+                f"Craft a comprehensive question of {difficulty} CEFR level "
+                "difficulty like the ones for IELTS Writing Task 2 General "
+                "Training that directs the candidate to delve into an in-depth "
+                "analysis of contrasting perspectives on the topic of "
+                f'"{topic}". The question should lead to an answer with either '
+                '"theories", "complicated information" or be "very descriptive" '
+                "on the topic."
+            )
+        else:
+            user_msg = (
+                "Analyze the uploaded image and create a detailed IELTS Writing "
+                "Task 1 Academic prompt. Describe the visual type, context, and "
+                f"create a prompt at {difficulty} CEFR level."
+            )
+
+        return self.ai.prediction(
+            model=GPT_MODELS["generation"],
+            messages=[
+                {"role": "system", "content": system_msg},
+                {"role": "user", "content": user_msg},
+            ],
+            temperature=TEMPERATURE["generation"],
+            fields_to_check=["question"],
+        )
+
+    # ------------------------------------------------------------------
+    # Speaking
+    # ------------------------------------------------------------------
+
+    def generate_speaking_task(
+        self,
+        part,
+        topic=None,
+        first_topic=None,
+        second_topic=None,
+        difficulty=None,
+    ):
+        """Generate a speaking task for the given part (1, 2, or 3)."""
+        system_msg = (
+            "You are a helpful assistant designed to output JSON. "
+            "Generate IELTS speaking task questions."
+        )
+
+        if part == 1:
+            first_topic = first_topic or random.choice(TOPICS)
+            second_topic = second_topic or random.choice(TOPICS)
+            user_msg = (
+                "Craft 5 simple and single questions of easy difficulty for "
+                "IELTS Speaking Part 1 that encourages candidates to delve "
+                "deeply into personal experiences, preferences, or insights "
+                f'on the topic of "{first_topic}" and the topic of '
+                f'"{second_topic}". The questions should lead to the usage '
+                "of 4 verb tenses (present perfect, present, past and future). "
+                "Make sure that the generated question does not contain "
+                "forbidden subjects in muslim countries."
+            )
+        elif part == 2:
+            topic = topic or random.choice(TOPICS)
+            user_msg = (
+                "Create a question of medium difficulty for IELTS Speaking "
+                "Part 2 that encourages candidates to narrate a personal "
+                f'experience or story related to the topic of "{topic}". '
+                "Include 3 prompts that guide the candidate. The prompts "
+                "must not be questions. Also include a suffix like the ones "
+                'in the IELTS exams that start with "And explain why". '
+                "Make sure that the generated question does not contain "
+                "forbidden subjects in muslim countries."
+            )
+        else:
+            topic = topic or random.choice(TOPICS)
+            user_msg = (
+                "Formulate a set of 5 single questions of hard difficulty "
+                "for IELTS Speaking Part 3 that encourage candidates to "
+                "engage in a meaningful discussion on the topic of "
+                f'"{topic}". They must be 1 single question each and not '
+                "be double-barreled questions. Make sure that the generated "
+                "question does not contain forbidden subjects in muslim countries."
+            )
+
+        if difficulty:
+            user_msg += f" Target CEFR level: {difficulty}."
+
+        return self.ai.prediction(
+            model=GPT_MODELS["generation"],
+            messages=[
+                {"role": "system", "content": system_msg},
+                {"role": "user", "content": user_msg},
+            ],
+            temperature=TEMPERATURE["generation"],
+        )
+
+    # ------------------------------------------------------------------
+    # Level exercises
+    # ------------------------------------------------------------------
+
+    def generate_level_exercises(self, exercises_config, difficulty):
+        """Generate level-exam exercises (multiple choice, fill-blanks, etc.).
+
+        exercises_config: list of dicts with 'type', 'quantity', and optional
+            'topic', 'size' keys.
+        difficulty: CEFR level string.
+        """
+        system_msg = (
+            "You are a helpful assistant designed to output JSON. "
+            "Generate English level exam exercises."
+        )
+
+        prompts = []
+        for cfg in exercises_config:
+            ex_type = cfg.get("type", "multiple_choice")
+            quantity = cfg.get("quantity", 5)
+            topic = cfg.get("topic") or random.choice(TOPICS)
+            size = cfg.get("size", 200)
+
+            if ex_type == "multiple_choice":
+                prompts.append(
+                    f"Generate {quantity} multiple choice questions of 4 options "
+                    f"for an english level exam of {difficulty} CEFR level. "
+                    "Ensure that the questions cover a range of topics such as "
+                    "verb tense, subject-verb agreement, pronoun usage, sentence "
+                    "structure, and punctuation. Make sure every question only has "
+                    "1 correct answer."
+                )
+            elif ex_type == "fill_blanks":
+                prompts.append(
+                    f"Generate a text of at least {size} words about the topic "
+                    f"{topic}. From the generated text choose exactly {quantity} "
+                    "words (cannot be sequential words), replace each with "
+                    "{id}, and generate a JSON object containing: the modified "
+                    "text, solutions array, words array with four options per blank."
+                )
+
+        user_msg = "\n\n".join(prompts)
+
+        return self.ai.prediction(
+            model=GPT_MODELS["generation"],
+            messages=[
+                {"role": "system", "content": system_msg},
+                {"role": "user", "content": user_msg},
+            ],
+            temperature=TEMPERATURE["generation"],
+        )

encoach_ai_grading/__init__.py

@@ -0,0 +1 @@
+from . import services

encoach_ai_grading/__manifest__.py

@@ -0,0 +1,13 @@
+{
+    "name": "EnCoach AI Grading",
+    "version": "19.0.1.0.0",
+    "category": "Education",
+    "summary": "AI-powered IELTS grading for writing and speaking",
+    "description": "GPT-4o grading with IELTS rubrics, GPTZero AI detection, short-answer evaluation.",
+    "depends": ["encoach_ai", "encoach_exam"],
+    "data": [
+        "security/ir.model.access.csv",
+    ],
+    "installable": True,
+    "license": "LGPL-3",
+}

encoach_ai_grading/security/ir.model.access.csv

@@ -0,0 +1 @@
+id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink

encoach_ai_grading/services/__init__.py

@@ -0,0 +1 @@
+from . import grading_service

encoach_ai_grading/services/grading_service.py

@@ -0,0 +1,340 @@
+import json
+import logging
+
+import httpx
+
+from odoo.addons.encoach_ai.models.constants import GPT_MODELS, TEMPERATURE
+from odoo.addons.encoach_ai.services.openai_service import EncoachOpenAIService
+
+_logger = logging.getLogger(__name__)
+
+WRITING_RESPONSE_TEMPLATE = json.dumps({
+    "comment": "comment about student's response quality",
+    "overall": 0.0,
+    "task_response": {
+        "Task Achievement": {"grade": 0.0, "comment": "..."},
+        "Coherence and Cohesion": {"grade": 0.0, "comment": "..."},
+        "Lexical Resource": {"grade": 0.0, "comment": "..."},
+        "Grammatical Range and Accuracy": {"grade": 0.0, "comment": "..."},
+    },
+})
+
+SPEAKING_RESPONSE_TEMPLATE = json.dumps({
+    "comment": "extensive comment about answer quality",
+    "overall": 0.0,
+    "task_response": {
+        "Fluency and Coherence": {"grade": 0.0, "comment": "extensive comment..."},
+        "Lexical Resource": {"grade": 0.0, "comment": "..."},
+        "Grammatical Range and Accuracy": {"grade": 0.0, "comment": "..."},
+        "Pronunciation": {"grade": 0.0, "comment": "..."},
+    },
+})
+
+SHORT_ANSWER_TEMPLATE = json.dumps({
+    "exercises": [
+        {"id": "exercise-id", "correct": True, "correct_answer": "the correct answer"},
+    ],
+})
+
+SUMMARY_TEMPLATE = json.dumps({
+    "sections": [
+        {
+            "code": "section-code",
+            "name": "Section Name",
+            "grade": 0.0,
+            "evaluation": "Detailed evaluation text...",
+            "suggestions": "Improvement suggestions...",
+            "bullet_points": ["point 1", "point 2"],
+        },
+    ],
+})
+
+SPEAKING_TASK_INSTRUCTIONS = {
+    1: (
+        'Address the student as "you". '
+        "If the answers are not 2 or 3 sentences long, "
+        "warn the student that they should be."
+    ),
+    2: 'Address the student as "you".',
+    3: (
+        'Address the student as "you" and pay special attention '
+        "to coherence between the answers."
+    ),
+}
+
+
+class EncoachGradingService:
+
+    def __init__(self, env):
+        self.env = env
+        self.ai = EncoachOpenAIService(env)
+
+    # ------------------------------------------------------------------
+    # Writing grading
+    # ------------------------------------------------------------------
+
+    def grade_writing(self, question, answer, task, attachment=None):
+        """Grade a writing answer using GPT-4o with IELTS writing rubric.
+
+        Returns dict with comment, overall, task_response, fixed_text,
+        perfect_answer, and ai_detection results.
+        """
+        system_msg = (
+            "You are a helpful assistant designed to output JSON "
+            f"on this format: {WRITING_RESPONSE_TEMPLATE}"
+        )
+
+        if task == 1:
+            user_prompt = (
+                f"Evaluate the given Writing Task {task} response based on the "
+                "IELTS grading system, ensuring a strict assessment that penalizes "
+                "errors. Deduct points for deviations from the task, and assign a "
+                "score of 0 if the response fails to address the question. "
+                "Additionally, provide a detailed commentary highlighting both "
+                "strengths and weaknesses in the response.\n"
+                'Refer to the parts of the letter as: "Greeting Opener", '
+                '"bullet 1", "bullet 2", "bullet 3", '
+                '"closer (restate the purpose of the letter)", "closing greeting".\n'
+                f'Question: "{question}"\nAnswer: "{answer}"'
+            )
+        else:
+            user_prompt = (
+                f"Evaluate the given Writing Task {task} response based on the "
+                "IELTS grading system, ensuring a strict assessment that penalizes "
+                "errors. Deduct points for deviations from the task, and assign a "
+                "score of 0 if the response fails to address the question. "
+                "Additionally, provide a detailed commentary highlighting both "
+                "strengths and weaknesses in the response.\n"
+                f'Question: "{question}"\nAnswer: "{answer}"'
+            )
+
+        messages = [
+            {"role": "system", "content": system_msg},
+        ]
+
+        if attachment and task == 1:
+            messages.append({
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": user_prompt},
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": attachment},
+                    },
+                ],
+            })
+        else:
+            messages.append({"role": "user", "content": user_prompt})
+
+        result = self.ai.prediction(
+            model=GPT_MODELS["grading"],
+            messages=messages,
+            temperature=TEMPERATURE["grading"],
+            fields_to_check=["comment"],
+        )
+        if not result:
+            return None
+
+        result["fixed_text"] = self._get_fixed_text(answer)
+        result["perfect_answer"] = self._get_perfect_answer(question)
+        result["ai_detection"] = self._detect_ai(answer)
+        return result
+
+    # ------------------------------------------------------------------
+    # Speaking grading
+    # ------------------------------------------------------------------
+
+    def grade_speaking(self, task, qa_pairs):
+        """Grade speaking using GPT-4o with IELTS speaking rubric.
+
+        qa_pairs: list of dicts with 'question' and 'answer' keys.
+        """
+        system_msg = (
+            "You are a helpful assistant designed to output JSON "
+            f"on this format: {SPEAKING_RESPONSE_TEMPLATE}"
+        )
+
+        qa_text = "\n".join(
+            f'Question: "{p["question"]}"\nAnswer: "{p["answer"]}"'
+            for p in qa_pairs
+        )
+        task_instruction = SPEAKING_TASK_INSTRUCTIONS.get(task, "")
+
+        user_prompt = (
+            f"Evaluate the given Speaking Part {task} response based on the "
+            "IELTS grading system, ensuring a strict assessment that penalizes "
+            "errors. Deduct points for deviations from the task, and assign a "
+            "score of 0 if the response fails to address the question. "
+            "Additionally, provide detailed commentary highlighting both "
+            f"strengths and weaknesses in the response. {task_instruction}\n"
+            f"{qa_text}"
+        )
+
+        messages = [
+            {"role": "system", "content": system_msg},
+            {"role": "user", "content": user_prompt},
+        ]
+
+        result = self.ai.prediction(
+            model=GPT_MODELS["grading"],
+            messages=messages,
+            temperature=TEMPERATURE["grading"],
+            fields_to_check=["comment"],
+        )
+        if not result:
+            return None
+
+        if task == 2 and qa_pairs:
+            combined_answer = " ".join(p["answer"] for p in qa_pairs)
+            result["fixed_text"] = self._get_fixed_text(combined_answer)
+            result["perfect_answer"] = self._get_perfect_answer(
+                qa_pairs[0]["question"]
+            )
+        return result
+
+    # ------------------------------------------------------------------
+    # Short-answer grading
+    # ------------------------------------------------------------------
+
+    def grade_short_answers(self, text, questions, answers):
+        """Evaluate short answers against a reading/listening passage."""
+        system_msg = (
+            "You are a helpful assistant designed to output JSON "
+            f"on this format: {SHORT_ANSWER_TEMPLATE}"
+        )
+
+        qa_text = "\n".join(
+            f'Q{i + 1}: "{q}" — Student answer: "{a}"'
+            for i, (q, a) in enumerate(zip(questions, answers))
+        )
+
+        user_prompt = (
+            "Evaluate each student answer against the passage. For each answer, "
+            "determine if it is correct and provide the correct answer.\n\n"
+            f'Passage: "{text}"\n\n{qa_text}'
+        )
+
+        messages = [
+            {"role": "system", "content": system_msg},
+            {"role": "user", "content": user_prompt},
+        ]
+
+        return self.ai.prediction(
+            model=GPT_MODELS["grading"],
+            messages=messages,
+            temperature=TEMPERATURE["grading"],
+            check_blacklisted=False,
+        )
+
+    # ------------------------------------------------------------------
+    # Grading summary
+    # ------------------------------------------------------------------
+
+    def generate_grading_summary(self, sections):
+        """Generate a summary for an entire exam session using GPT-3.5-turbo."""
+        system_msg = (
+            "You are a helpful assistant designed to output JSON "
+            f"on this format: {SUMMARY_TEMPLATE}"
+        )
+
+        user_prompt = (
+            "Generate a detailed evaluation summary for the following IELTS exam "
+            "sections. For each section, provide an evaluation, suggestions for "
+            "improvement, and key bullet points.\n\n"
+            + json.dumps(sections)
+        )
+
+        messages = [
+            {"role": "system", "content": system_msg},
+            {"role": "user", "content": user_prompt},
+        ]
+
+        return self.ai.prediction(
+            model=GPT_MODELS["secondary"],
+            messages=messages,
+            temperature=TEMPERATURE["grading"],
+            check_blacklisted=False,
+        )
+
+    # ------------------------------------------------------------------
+    # AI detection (GPTZero)
+    # ------------------------------------------------------------------
+
+    def _detect_ai(self, text):
+        """Call GPTZero API to detect AI-generated text."""
+        api_key = (
+            self.env["ir.config_parameter"]
+            .sudo()
+            .get_param("encoach.gptzero_api_key", "")
+        )
+        if not api_key:
+            _logger.warning("GPTZero API key not configured")
+            return None
+
+        try:
+            resp = httpx.post(
+                "https://api.gptzero.me/v2/predict/text",
+                headers={
+                    "x-api-key": api_key,
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "document": text,
+                    "version": "",
+                    "multilingual": False,
+                },
+                timeout=30,
+            )
+            resp.raise_for_status()
+            return resp.json()
+        except Exception:
+            _logger.exception("GPTZero API call failed")
+            return None
+
+    # ------------------------------------------------------------------
+    # Helper prompts
+    # ------------------------------------------------------------------
+
+    def _get_perfect_answer(self, question):
+        messages = [
+            {"role": "system", "content": "You are an IELTS writing expert."},
+            {
+                "role": "user",
+                "content": (
+                    "Write a perfect answer for this IELTS writing task: "
+                    f'"{question}"'
+                ),
+            },
+        ]
+        result = self.ai.prediction(
+            model=GPT_MODELS["secondary"],
+            messages=messages,
+            temperature=TEMPERATURE["grading"],
+            response_format={"type": "json_object"},
+            check_blacklisted=False,
+        )
+        if result and "answer" in result:
+            return result["answer"]
+        return result
+
+    def _get_fixed_text(self, text):
+        messages = [
+            {"role": "system", "content": "You are a grammar correction assistant. Output JSON."},
+            {
+                "role": "user",
+                "content": (
+                    "Fix the grammatical and spelling errors in this text, "
+                    f'keeping the original meaning: "{text}"'
+                ),
+            },
+        ]
+        result = self.ai.prediction(
+            model=GPT_MODELS["secondary"],
+            messages=messages,
+            temperature=TEMPERATURE["grading"],
+            response_format={"type": "json_object"},
+            check_blacklisted=False,
+        )
+        if result and "text" in result:
+            return result["text"]
+        return result

encoach_ai_media/__init__.py

@@ -0,0 +1,2 @@
+from . import models
+from . import services

encoach_ai_media/__manifest__.py

@@ -0,0 +1,17 @@
+{
+    "name": "EnCoach AI Media",
+    "version": "19.0.1.0.0",
+    "category": "Education",
+    "summary": "TTS, STT, and video generation for EnCoach",
+    "description": "AWS Polly TTS, OpenAI Whisper STT, ELAI avatar video generation.",
+    "depends": ["encoach_ai"],
+    "data": [
+        "security/ir.model.access.csv",
+        "views/avatar_views.xml",
+    ],
+    "installable": True,
+    "license": "LGPL-3",
+    "external_dependencies": {
+        "python": ["boto3"],
+    },
+}

encoach_ai_media/models/__init__.py

@@ -0,0 +1 @@
+from . import elai_avatar

encoach_ai_media/models/elai_avatar.py

@@ -0,0 +1,30 @@
+from odoo import models, fields
+
+
+class EncoachElaiAvatar(models.Model):
+    _name = "encoach.elai.avatar"
+    _description = "ELAI Avatar Configuration"
+
+    name = fields.Char(required=True)
+    avatar_code = fields.Char(required=True)
+    avatar_url = fields.Char()
+    gender = fields.Selection(
+        [("male", "Male"), ("female", "Female")],
+        string="Gender",
+    )
+    canvas = fields.Char()
+    voice_id = fields.Char()
+    voice_provider = fields.Char()
+
+    def to_encoach_dict(self):
+        self.ensure_one()
+        return {
+            "id": self.id,
+            "name": self.name,
+            "avatarCode": self.avatar_code,
+            "avatarUrl": self.avatar_url or "",
+            "gender": self.gender or "",
+            "canvas": self.canvas or "",
+            "voiceId": self.voice_id or "",
+            "voiceProvider": self.voice_provider or "",
+        }

encoach_ai_media/security/ir.model.access.csv

@@ -0,0 +1,4 @@
+id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
+access_encoach_elai_avatar_student,encoach.elai.avatar.student,model_encoach_elai_avatar,encoach_core.group_encoach_student,1,0,0,0
+access_encoach_elai_avatar_admin,encoach.elai.avatar.admin,model_encoach_elai_avatar,encoach_core.group_encoach_admin,1,1,1,1
+access_encoach_elai_avatar_sysadmin,encoach.elai.avatar.sysadmin,model_encoach_elai_avatar,base.group_system,1,1,1,1

encoach_ai_media/services/__init__.py

@@ -0,0 +1,3 @@
+from . import polly_service
+from . import whisper_service
+from . import elai_service

encoach_ai_media/services/elai_service.py

@@ -0,0 +1,107 @@
+import logging
+
+import httpx
+
+_logger = logging.getLogger(__name__)
+
+ELAI_BASE_URL = "https://apis.elai.io/api/v1/videos"
+
+
+class EncoachElaiService:
+
+    def __init__(self, env):
+        self.env = env
+        self.token = (
+            env["ir.config_parameter"]
+            .sudo()
+            .get_param("encoach.elai_token", "")
+        )
+
+    def _headers(self):
+        return {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+        }
+
+    def create_video(self, text, avatar_code):
+        """Create and render an ELAI video.
+
+        Returns the video_id for status polling, or None on failure.
+        """
+        avatar = (
+            self.env["encoach.elai.avatar"]
+            .sudo()
+            .search([("avatar_code", "=", avatar_code)], limit=1)
+        )
+        if not avatar:
+            _logger.error("Avatar not found: %s", avatar_code)
+            return None
+
+        payload = {
+            "name": f"EnCoach Speaking - {avatar.name}",
+            "slides": [
+                {
+                    "avatar": {
+                        "code": avatar.avatar_code,
+                        "canvas": avatar.canvas or "default",
+                        "voiceId": avatar.voice_id or "",
+                        "voiceProvider": avatar.voice_provider or "",
+                    },
+                    "speech": text,
+                },
+            ],
+        }
+
+        try:
+            resp = httpx.post(
+                ELAI_BASE_URL,
+                headers=self._headers(),
+                json=payload,
+                timeout=30,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            video_id = data.get("_id") or data.get("id")
+
+            self._render_video(video_id)
+            return video_id
+        except Exception:
+            _logger.exception("ELAI video creation failed")
+            return None
+
+    def _render_video(self, video_id):
+        try:
+            httpx.post(
+                f"{ELAI_BASE_URL}/render/{video_id}",
+                headers=self._headers(),
+                timeout=30,
+            )
+        except Exception:
+            _logger.exception("ELAI render request failed for %s", video_id)
+
+    def poll_status(self, video_id):
+        """Poll ELAI for video rendering status.
+
+        Returns dict with 'status' and optionally 'url' keys.
+        """
+        try:
+            resp = httpx.get(
+                f"{ELAI_BASE_URL}/{video_id}",
+                headers=self._headers(),
+                timeout=30,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            status = data.get("status", "unknown")
+            result = {"status": status}
+            if status == "ready":
+                result["url"] = data.get("url", "")
+            return result
+        except Exception:
+            _logger.exception("ELAI status poll failed for %s", video_id)
+            return {"status": "error"}
+
+    def get_avatars(self):
+        """List all configured ELAI avatars."""
+        avatars = self.env["encoach.elai.avatar"].sudo().search([])
+        return [a.to_encoach_dict() for a in avatars]

encoach_ai_media/services/polly_service.py

@@ -0,0 +1,129 @@
+import io
+import logging
+import random
+import re
+
+import boto3
+
+_logger = logging.getLogger(__name__)
+
+POLLY_VOICES = {
+    "Danielle": {"gender": "Female", "accent": "US"},
+    "Gregory": {"gender": "Male", "accent": "US"},
+    "Kevin": {"gender": "Male", "accent": "US"},
+    "Ruth": {"gender": "Female", "accent": "US"},
+    "Stephen": {"gender": "Male", "accent": "US"},
+    "Arthur": {"gender": "Male", "accent": "GB"},
+    "Olivia": {"gender": "Female", "accent": "GB"},
+    "Ayanda": {"gender": "Female", "accent": "ZA"},
+    "Aria": {"gender": "Female", "accent": "NZ"},
+    "Kajal": {"gender": "Female", "accent": "IN"},
+    "Niamh": {"gender": "Female", "accent": "IE"},
+}
+
+FINAL_CUE_TEXT = (
+    "This audio recording, for the listening exercise, has finished."
+)
+FINAL_CUE_VOICE = "Stephen"
+
+MAX_CHUNK_SIZE = 3000
+
+
+class EncoachPollyService:
+
+    def __init__(self, env):
+        self.env = env
+        icp = env["ir.config_parameter"].sudo()
+        self.client = boto3.client(
+            "polly",
+            aws_access_key_id=icp.get_param("encoach.aws_access_key_id", ""),
+            aws_secret_access_key=icp.get_param("encoach.aws_secret_access_key", ""),
+            region_name=icp.get_param("encoach.aws_region", "us-east-1"),
+        )
+
+    def synthesize_speech(
+        self, text, voice, engine="neural", output_format="mp3"
+    ):
+        """Synthesize a single text block into MP3 bytes."""
+        chunks = self._chunk_text(text)
+        audio_parts = []
+        for chunk in chunks:
+            resp = self.client.synthesize_speech(
+                Text=chunk,
+                VoiceId=voice,
+                Engine=engine,
+                OutputFormat=output_format,
+            )
+            audio_parts.append(resp["AudioStream"].read())
+        return b"".join(audio_parts)
+
+    def text_to_speech(self, dialog, include_final_cue=True):
+        """Generate full MP3 audio from a conversation or monologue.
+
+        dialog: either a string (monologue) or a list of dicts with
+            'name', 'gender', 'text' keys.
+        """
+        audio_segments = []
+
+        if isinstance(dialog, str):
+            voice = random.choice(list(POLLY_VOICES.keys()))
+            audio_segments.append(self.synthesize_speech(dialog, voice))
+        else:
+            voice_map = self._assign_voices(dialog)
+            for line in dialog:
+                voice = voice_map.get(line["name"], "Stephen")
+                audio_segments.append(
+                    self.synthesize_speech(line["text"], voice)
+                )
+
+        if include_final_cue:
+            audio_segments.append(
+                self.synthesize_speech(FINAL_CUE_TEXT, FINAL_CUE_VOICE)
+            )
+
+        return b"".join(audio_segments)
+
+    @staticmethod
+    def _assign_voices(dialog):
+        """Assign distinct Polly voices to each speaker based on gender."""
+        speakers = {}
+        male_voices = [v for v, info in POLLY_VOICES.items() if info["gender"] == "Male"]
+        female_voices = [v for v, info in POLLY_VOICES.items() if info["gender"] == "Female"]
+        male_idx, female_idx = 0, 0
+
+        for line in dialog:
+            name = line.get("name", "")
+            if name in speakers:
+                continue
+            gender = (line.get("gender") or "").lower()
+            if gender == "female" and female_idx < len(female_voices):
+                speakers[name] = female_voices[female_idx]
+                female_idx += 1
+            elif male_idx < len(male_voices):
+                speakers[name] = male_voices[male_idx]
+                male_idx += 1
+            else:
+                speakers[name] = random.choice(list(POLLY_VOICES.keys()))
+        return speakers
+
+    @staticmethod
+    def _chunk_text(text, max_size=MAX_CHUNK_SIZE):
+        """Split text at sentence boundaries respecting max chunk size."""
+        if len(text) <= max_size:
+            return [text]
+
+        sentences = re.split(r"(?<=[.!?])\s+", text)
+        chunks = []
+        current = ""
+
+        for sentence in sentences:
+            if len(current) + len(sentence) + 1 > max_size:
+                if current:
+                    chunks.append(current.strip())
+                current = sentence
+            else:
+                current = f"{current} {sentence}" if current else sentence
+
+        if current:
+            chunks.append(current.strip())
+        return chunks

encoach_ai_media/services/whisper_service.py

@@ -0,0 +1,167 @@
+import logging
+from concurrent.futures import ThreadPoolExecutor
+
+import numpy as np
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+from odoo.addons.encoach_ai.models.constants import GPT_MODELS, TEMPERATURE
+from odoo.addons.encoach_ai.services.openai_service import EncoachOpenAIService
+
+_logger = logging.getLogger(__name__)
+
+SAMPLE_RATE = 16000
+CHUNK_SAMPLES = 480000  # 30 seconds at 16 kHz
+OVERLAP_RATIO = 0.25
+WHISPER_OPTIONS = {
+    "fp16": False,
+    "language": "English",
+    "verbose": False,
+}
+
+OVERLAP_CLEANUP_PROMPT = (
+    "The following are two transcribed segments from the same audio. "
+    "They overlap at the boundary. Remove any duplicated words at the "
+    "junction and return the cleaned, combined text as JSON: "
+    '{"text": "cleaned text"}'
+)
+
+DIALOG_DETECTION_PROMPT = (
+    "You are a helpful assistant designed to output JSON on either one of "
+    "these formats:\n"
+    '1 - {"dialog": [{"name": "name", "gender": "gender", "text": "text"}]}\n'
+    '2 - {"dialog": "text"}\n\n'
+    "A transcription of an audio file will be provided to you. Based on that "
+    "transcription you will need to determine whether the transcription is a "
+    "conversation or a monologue. If it is a conversation, output format 1. "
+    "If it is a monologue, output format 2."
+)
+
+_model_pool = []
+_pool_executor = None
+_pool_lock = None
+
+
+def _get_pool(num_workers=4):
+    global _model_pool, _pool_executor, _pool_lock
+    import threading
+    if _pool_lock is None:
+        _pool_lock = threading.Lock()
+
+    with _pool_lock:
+        if _pool_executor is None:
+            import whisper
+            _logger.info("Loading %d Whisper model instances...", num_workers)
+            _model_pool = [whisper.load_model("base") for _ in range(num_workers)]
+            _pool_executor = ThreadPoolExecutor(max_workers=num_workers)
+            _logger.info("Whisper pool ready with %d workers", num_workers)
+    return _pool_executor, _model_pool
+
+
+class EncoachWhisperService:
+
+    def __init__(self, env):
+        self.env = env
+        self.ai = EncoachOpenAIService(env)
+        self._num_workers = int(
+            env["ir.config_parameter"].sudo().get_param("encoach.whisper_workers", "4")
+        )
+        self._worker_idx = 0
+        import threading
+        self._idx_lock = threading.Lock()
+
+    def _get_model(self):
+        executor, pool = _get_pool(self._num_workers)
+        with self._idx_lock:
+            idx = self._worker_idx % len(pool)
+            self._worker_idx += 1
+        return pool[idx]
+
+    def transcribe(self, audio_data):
+        if not isinstance(audio_data, np.ndarray):
+            audio_data = np.frombuffer(audio_data, dtype=np.float32)
+
+        audio_data = audio_data.astype(np.float32)
+        if audio_data.max() > 1.0:
+            audio_data = audio_data / np.abs(audio_data).max()
+
+        chunks = self._chunk_audio(audio_data)
+
+        if len(chunks) == 1:
+            return self._transcribe_chunk(chunks[0])
+
+        executor, pool = _get_pool(self._num_workers)
+        futures = []
+        for i, chunk in enumerate(chunks):
+            model = pool[i % len(pool)]
+            future = executor.submit(self._transcribe_chunk_with_model, chunk, model)
+            futures.append(future)
+
+        segments = [f.result() for f in futures]
+        return self._merge_segments(segments)
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
+    def _transcribe_chunk(self, chunk):
+        model = self._get_model()
+        result = model.transcribe(chunk, **WHISPER_OPTIONS)
+        return result.get("text", "").strip()
+
+    @staticmethod
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
+    def _transcribe_chunk_with_model(chunk, model):
+        result = model.transcribe(chunk, **WHISPER_OPTIONS)
+        return result.get("text", "").strip()
+
+    def _merge_segments(self, segments):
+        if len(segments) <= 1:
+            return segments[0] if segments else ""
+
+        merged = segments[0]
+        for i in range(1, len(segments)):
+            result = self.ai.prediction(
+                model=GPT_MODELS["grading"],
+                messages=[
+                    {"role": "system", "content": OVERLAP_CLEANUP_PROMPT},
+                    {
+                        "role": "user",
+                        "content": (
+                            f'Segment A (end): "...{merged[-200:]}"\n'
+                            f'Segment B (start): "{segments[i][:200]}..."'
+                        ),
+                    },
+                ],
+                temperature=TEMPERATURE["grading"],
+                check_blacklisted=False,
+            )
+            if result and "text" in result:
+                merged = result["text"]
+            else:
+                merged = f"{merged} {segments[i]}"
+        return merged
+
+    def detect_dialog(self, transcript):
+        return self.ai.prediction(
+            model=GPT_MODELS["grading"],
+            messages=[
+                {"role": "system", "content": DIALOG_DETECTION_PROMPT},
+                {"role": "user", "content": transcript},
+            ],
+            temperature=TEMPERATURE["grading"],
+            check_blacklisted=False,
+        )
+
+    @staticmethod
+    def _chunk_audio(audio, chunk_size=CHUNK_SAMPLES, overlap=OVERLAP_RATIO):
+        total = len(audio)
+        if total <= chunk_size:
+            return [audio]
+
+        step = int(chunk_size * (1 - overlap))
+        chunks = []
+        start = 0
+        while start < total:
+            end = min(start + chunk_size, total)
+            chunks.append(audio[start:end])
+            if end >= total:
+                break
+            start += step
+        return chunks

encoach_ai_media/views/avatar_views.xml

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <record id="view_encoach_elai_avatar_list" model="ir.ui.view">
+        <field name="name">encoach.elai.avatar.list</field>
+        <field name="model">encoach.elai.avatar</field>
+        <field name="arch" type="xml">
+            <list string="ELAI Avatars">
+                <field name="name"/>
+                <field name="avatar_code"/>
+                <field name="gender"/>
+                <field name="voice_id"/>
+                <field name="voice_provider"/>
+                <field name="canvas"/>
+            </list>
+        </field>
+    </record>
+
+    <record id="view_encoach_elai_avatar_form" model="ir.ui.view">
+        <field name="name">encoach.elai.avatar.form</field>
+        <field name="model">encoach.elai.avatar</field>
+        <field name="arch" type="xml">
+            <form string="ELAI Avatar">
+                <sheet>
+                    <group>
+                        <field name="name"/>
+                        <field name="avatar_code"/>
+                        <field name="avatar_url" widget="url"/>
+                        <field name="gender"/>
+                        <field name="canvas"/>
+                        <field name="voice_id"/>
+                        <field name="voice_provider"/>
+                    </group>
+                </sheet>
+            </form>
+        </field>
+    </record>
+
+    <record id="action_encoach_elai_avatar" model="ir.actions.act_window">
+        <field name="name">ELAI Avatars</field>
+        <field name="res_model">encoach.elai.avatar</field>
+        <field name="view_mode">list,form</field>
+    </record>
+
+    <menuitem id="menu_encoach_elai_avatar"
+        name="ELAI Avatars"
+        parent="encoach_core.menu_encoach_config"
+        action="action_encoach_elai_avatar"
+        sequence="10"/>
+</odoo>

encoach_api/__init__.py

@@ -0,0 +1 @@
+from . import controllers

encoach_api/__manifest__.py

@@ -0,0 +1,29 @@
+{
+    "name": "EnCoach API",
+    "version": "19.0.1.0.0",
+    "category": "Education",
+    "summary": "REST JSON API controllers for the EnCoach platform",
+    "depends": [
+        "encoach_core",
+        "encoach_exam",
+        "encoach_classroom",
+        "encoach_assignment",
+        "encoach_stats",
+        "encoach_evaluation",
+        "encoach_training",
+        "encoach_subscription",
+        "encoach_registration",
+        "encoach_ticket",
+        "encoach_ai_grading",
+        "encoach_ai_generation",
+        "encoach_ai_media",
+    ],
+    "data": [
+        "security/ir.model.access.csv",
+    ],
+    "installable": True,
+    "license": "LGPL-3",
+    "external_dependencies": {
+        "python": ["jwt"],
+    },
+}

encoach_api/controllers/__init__.py

@@ -0,0 +1,20 @@
+from . import base
+from . import auth
+from . import users
+from . import exams
+from . import classrooms
+from . import assignments
+from . import sessions
+from . import stats
+from . import evaluations
+from . import training
+from . import subscriptions
+from . import registration
+from . import tickets
+from . import storage
+from . import grading
+from . import generation
+from . import media
+from . import entities
+from . import discounts
+from . import approvals

encoach_api/controllers/approvals.py

@@ -0,0 +1,89 @@
+import json
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class ApprovalsController(EncoachMixin, http.Controller):
+
+    @http.route('/api/approval-workflows', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def list_workflows(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            workflows = request.env['encoach.approval.workflow'].sudo().search([])
+            return self._json_response([{
+                'id': w.id, 'examId': w.exam_id.id if w.exam_id else None,
+                'creatorId': w.creator_id.id if w.creator_id else None,
+                'status': w.status, 'modules': w.modules, 'steps': w.steps,
+            } for w in workflows])
+        except Exception:
+            _logger.exception("List approval workflows error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/approval-workflows', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def create_workflow(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            body = self._get_json_body()
+            vals = {
+                'creator_id': user.id,
+                'status': body.get('status', 'pending'),
+            }
+            if body.get('examId'): vals['exam_id'] = int(body['examId'])
+            if 'modules' in body: vals['modules'] = body['modules']
+            if 'steps' in body: vals['steps'] = body['steps']
+            wf = request.env['encoach.approval.workflow'].sudo().create(vals)
+            return self._json_response({
+                'id': wf.id, 'examId': wf.exam_id.id if wf.exam_id else None,
+                'status': wf.status,
+            })
+        except Exception:
+            _logger.exception("Create approval workflow error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/approval-workflows/<int:wid>', type='http', auth='public', methods=['PATCH', 'OPTIONS'], csrf=False, cors='*')
+    def update_workflow(self, wid, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            wf = request.env['encoach.approval.workflow'].sudo().browse(wid)
+            if not wf.exists():
+                return self._error_response('Workflow not found', 404)
+            body = self._get_json_body()
+            vals = {}
+            if 'status' in body: vals['status'] = body['status']
+            if 'modules' in body: vals['modules'] = body['modules']
+            if 'steps' in body: vals['steps'] = body['steps']
+            if vals:
+                wf.write(vals)
+            return self._json_response({
+                'id': wf.id, 'status': wf.status,
+            })
+        except Exception:
+            _logger.exception("Update approval workflow error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/approval-workflows/<int:wid>', type='http', auth='public', methods=['DELETE', 'OPTIONS'], csrf=False, cors='*')
+    def delete_workflow(self, wid, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            wf = request.env['encoach.approval.workflow'].sudo().browse(wid)
+            if not wf.exists():
+                return self._error_response('Workflow not found', 404)
+            wf.unlink()
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Delete approval workflow error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/assignments.py

@@ -0,0 +1,235 @@
+import json
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class AssignmentsController(EncoachMixin, http.Controller):
+
+    # --------------------------------------------------------------- list
+    @http.route('/api/assignments', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def list_assignments(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            domain = []
+
+            group_id = kwargs.get('groupId')
+            if group_id:
+                domain.append(('group_id', '=', int(group_id)))
+
+            creator = kwargs.get('createdBy')
+            if creator:
+                domain.append(('create_uid', '=', int(creator)))
+
+            status = kwargs.get('status')
+            if status:
+                domain.append(('status', '=', status))
+
+            participant = kwargs.get('participant')
+            if participant:
+                domain.append(('group_id.participant_ids', 'in', [int(participant)]))
+
+            is_archived = kwargs.get('isArchived')
+            if is_archived is not None:
+                domain.append(('is_archived', '=', is_archived in ('true', '1', True)))
+
+            offset, limit, page = self._paginate_params(kwargs)
+            Assignment = request.env['encoach.assignment'].sudo()
+            total = Assignment.search_count(domain)
+            records = Assignment.search(domain, offset=offset, limit=limit, order='create_date desc')
+
+            return self._json_response({
+                'assignments': [self._serialize_assignment(a) for a in records],
+                'total': total,
+                'page': page,
+                'limit': limit,
+            })
+        except Exception:
+            _logger.exception("List assignments error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------------------------- create
+    @http.route('/api/assignments', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def create_assignment(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            if not body.get('examId'):
+                return self._error_response('examId is required', 400)
+            if not body.get('groupId'):
+                return self._error_response('groupId is required', 400)
+
+            vals = {
+                'name': body.get('name', ''),
+                'exam_id': int(body['examId']),
+                'group_id': int(body['groupId']),
+                'status': 'draft',
+            }
+            if body.get('startDate'):
+                vals['start_date'] = body['startDate']
+            if body.get('endDate'):
+                vals['end_date'] = body['endDate']
+            if body.get('duration'):
+                vals['duration'] = int(body['duration'])
+
+            assignment = request.env['encoach.assignment'].sudo().with_user(user).create(vals)
+            return self._json_response(self._serialize_assignment(assignment), status=201)
+        except Exception:
+            _logger.exception("Create assignment error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------------------------- update
+    @http.route(
+        '/api/assignments/<int:aid>', type='http', auth='public',
+        methods=['PATCH', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def update_assignment(self, aid, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            assignment = request.env['encoach.assignment'].sudo().browse(aid)
+            if not assignment.exists():
+                return self._error_response('Assignment not found', 404)
+
+            body = self._get_json_body()
+            vals = {}
+            if 'name' in body:
+                vals['name'] = body['name']
+            if 'startDate' in body:
+                vals['start_date'] = body['startDate']
+            if 'endDate' in body:
+                vals['end_date'] = body['endDate']
+            if 'duration' in body:
+                vals['duration'] = int(body['duration'])
+            if 'examId' in body:
+                vals['exam_id'] = int(body['examId'])
+            if 'groupId' in body:
+                vals['group_id'] = int(body['groupId'])
+            if 'status' in body:
+                vals['status'] = body['status']
+
+            if vals:
+                assignment.write(vals)
+
+            return self._json_response(self._serialize_assignment(assignment))
+        except Exception:
+            _logger.exception("Update assignment error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------------------------- delete
+    @http.route(
+        '/api/assignments/<int:aid>', type='http', auth='public',
+        methods=['DELETE', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def delete_assignment(self, aid, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            assignment = request.env['encoach.assignment'].sudo().browse(aid)
+            if not assignment.exists():
+                return self._error_response('Assignment not found', 404)
+
+            assignment.unlink()
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Delete assignment error")
+            return self._error_response('Internal server error', 500)
+
+    # --------------------------------------------------------------- start
+    @http.route(
+        '/api/assignments/<int:aid>/start', type='http', auth='public',
+        methods=['POST', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def start_assignment(self, aid, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            assignment = request.env['encoach.assignment'].sudo().browse(aid)
+            if not assignment.exists():
+                return self._error_response('Assignment not found', 404)
+
+            assignment.action_start()
+            return self._json_response(self._serialize_assignment(assignment))
+        except Exception as exc:
+            _logger.exception("Start assignment error")
+            return self._error_response(str(exc) if str(exc) != '' else 'Internal server error', 500)
+
+    # ------------------------------------------------------------- release
+    @http.route(
+        '/api/assignments/<int:aid>/release', type='http', auth='public',
+        methods=['POST', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def release_assignment(self, aid, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            assignment = request.env['encoach.assignment'].sudo().browse(aid)
+            if not assignment.exists():
+                return self._error_response('Assignment not found', 404)
+
+            assignment.action_release()
+            return self._json_response(self._serialize_assignment(assignment))
+        except Exception as exc:
+            _logger.exception("Release assignment error")
+            return self._error_response(str(exc) if str(exc) != '' else 'Internal server error', 500)
+
+    # ------------------------------------------------------------- archive
+    @http.route(
+        '/api/assignments/<int:aid>/archive', type='http', auth='public',
+        methods=['POST', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def archive_assignment(self, aid, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            assignment = request.env['encoach.assignment'].sudo().browse(aid)
+            if not assignment.exists():
+                return self._error_response('Assignment not found', 404)
+
+            assignment.write({'is_archived': True})
+            return self._json_response(self._serialize_assignment(assignment))
+        except Exception:
+            _logger.exception("Archive assignment error")
+            return self._error_response('Internal server error', 500)
+
+    # ----------------------------------------------------------- unarchive
+    @http.route(
+        '/api/assignments/<int:aid>/unarchive', type='http', auth='public',
+        methods=['POST', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def unarchive_assignment(self, aid, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            assignment = request.env['encoach.assignment'].sudo().browse(aid)
+            if not assignment.exists():
+                return self._error_response('Assignment not found', 404)
+
+            assignment.write({'is_archived': False})
+            return self._json_response(self._serialize_assignment(assignment))
+        except Exception:
+            _logger.exception("Unarchive assignment error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/auth.py

@@ -0,0 +1,110 @@
+import logging
+from datetime import datetime, timedelta
+
+import jwt as pyjwt
+
+from odoo import http
+from odoo.exceptions import AccessDenied
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class AuthController(EncoachMixin, http.Controller):
+
+    def _create_jwt(self, user, secret, expires_hours=72):
+        payload = {
+            'user_id': user.id,
+            'email': user.login,
+            'iat': datetime.utcnow(),
+            'exp': datetime.utcnow() + timedelta(hours=expires_hours),
+        }
+        return pyjwt.encode(payload, secret, algorithm='HS256')
+
+    @http.route('/api/login', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def login(self, **kwargs):
+        try:
+            body = self._get_json_body()
+            email = (body.get('credential') or body.get('email') or '').strip()
+            password = body.get('password', '')
+            if not email or not password:
+                return self._error_response('Email and password are required', 400)
+
+            user = request.env['res.users'].sudo().search([
+                ('login', '=', email),
+            ], limit=1)
+            if not user:
+                return self._error_response('Invalid email or password', 401)
+
+            try:
+                credential = {'type': 'password', 'login': email, 'password': password}
+                request.env['res.users'].sudo().authenticate(
+                    credential, {'interactive': False},
+                )
+            except AccessDenied:
+                return self._error_response('Invalid email or password', 401)
+
+            secret = request.env['ir.config_parameter'].sudo().get_param('encoach.jwt_secret')
+            if not secret:
+                return self._error_response('Server configuration error', 500)
+
+            token = self._create_jwt(user, secret)
+            return self._json_response({
+                'user': self._serialize(user),
+                'token': token,
+            })
+        except Exception:
+            _logger.exception("Login error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/logout', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def logout(self, **kwargs):
+        try:
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Logout error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/reset', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def reset_password(self, **kwargs):
+        try:
+            body = self._get_json_body()
+            email = body.get('email', '').strip()
+            new_password = body.get('password', '')
+            token = body.get('token', '')
+            if not email:
+                return self._error_response('Email is required', 400)
+
+            user = request.env['res.users'].sudo().search([('login', '=', email)], limit=1)
+            if not user:
+                return self._json_response({'ok': True})
+
+            if token and new_password:
+                secret = request.env['ir.config_parameter'].sudo().get_param('encoach.jwt_secret')
+                try:
+                    payload = pyjwt.decode(token, secret, algorithms=['HS256'])
+                except pyjwt.InvalidTokenError:
+                    return self._error_response('Invalid or expired reset token', 400)
+                if payload.get('user_id') != user.id or payload.get('purpose') != 'password_reset':
+                    return self._error_response('Invalid reset token', 400)
+                user.sudo().write({'password': new_password})
+                return self._json_response({'ok': True})
+
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Password reset error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/reset/sendVerification', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def send_verification(self, **kwargs):
+        try:
+            body = self._get_json_body()
+            email = body.get('email', '').strip()
+            if not email:
+                return self._error_response('Email is required', 400)
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Send verification error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/base.py

@@ -0,0 +1,73 @@
+import json
+import logging
+
+import jwt as pyjwt
+
+from odoo.http import request
+
+_logger = logging.getLogger(__name__)
+
+
+class EncoachMixin:
+    """Shared authentication and response helpers for all EnCoach API controllers."""
+
+    def _authenticate(self):
+        """Decode JWT Bearer token and return the corresponding ``res.users`` record.
+
+        Returns ``None`` when the token is missing, expired or invalid.
+        """
+        auth_header = request.httprequest.headers.get("Authorization", "")
+        if not auth_header.startswith("Bearer "):
+            return None
+        token = auth_header[7:]
+        secret = (
+            request.env["ir.config_parameter"]
+            .sudo()
+            .get_param("encoach.jwt_secret")
+        )
+        if not secret:
+            _logger.error("System parameter 'encoach.jwt_secret' is not configured")
+            return None
+        try:
+            payload = pyjwt.decode(token, secret, algorithms=["HS256"])
+        except pyjwt.ExpiredSignatureError:
+            return None
+        except pyjwt.InvalidTokenError:
+            return None
+        user_id = payload.get("user_id")
+        if not user_id:
+            return None
+        user = request.env["res.users"].sudo().browse(int(user_id))
+        if not user.exists():
+            return None
+        return user
+
+    def _json_response(self, data, status=200):
+        return request.make_json_response(data, status=status)
+
+    def _error_response(self, message, status=400, code=None):
+        body = {"error": message}
+        if code:
+            body["code"] = code
+        return request.make_json_response(body, status=status)
+
+    def _get_json_body(self):
+        try:
+            return json.loads(request.httprequest.get_data(as_text=True))
+        except (ValueError, TypeError):
+            return {}
+
+    def _paginate_params(self, kwargs):
+        page = max(int(kwargs.get("page", 1)), 1)
+        limit = min(max(int(kwargs.get("limit", 20)), 1), 100)
+        offset = (page - 1) * limit
+        return offset, limit, page
+
+    def _serialize(self, record):
+        """Delegate to the record's own to_encoach_dict() if available."""
+        if hasattr(record, "to_encoach_dict"):
+            return record.to_encoach_dict()
+        return {"id": record.id}
+
+    def _serialize_list(self, records):
+        return [self._serialize(r) for r in records]

encoach_api/controllers/classrooms.py

@@ -0,0 +1,122 @@
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class ClassroomsController(EncoachMixin, http.Controller):
+
+    # --------------------------------------------------------------- list
+    @http.route('/api/groups', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def list_groups(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            domain = []
+            participant = kwargs.get('participant')
+            if participant:
+                domain.append(('participant_ids', 'in', [int(participant)]))
+
+            admin = kwargs.get('admin')
+            if admin:
+                domain.append(('admin_ids', 'in', [int(admin)]))
+
+            entity_id = kwargs.get('entityID')
+            if entity_id:
+                domain.append(('entity_id', '=', int(entity_id)))
+
+            groups = request.env['encoach.group'].sudo().search(domain, order='name asc')
+            return self._json_response([self._serialize_group(g) for g in groups])
+        except Exception:
+            _logger.exception("List groups error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------------------------- create
+    @http.route('/api/groups', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def create_group(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            if not body.get('name'):
+                return self._error_response('Group name is required', 400)
+
+            vals = {
+                'name': body['name'],
+                'admin_ids': [(4, user.id)],
+            }
+            if body.get('entityID'):
+                vals['entity_id'] = int(body['entityID'])
+
+            participant_ids = body.get('participants', [])
+            if participant_ids:
+                vals['participant_ids'] = [(4, int(pid)) for pid in participant_ids]
+
+            group = request.env['encoach.group'].sudo().create(vals)
+            return self._json_response(self._serialize_group(group), status=201)
+        except Exception:
+            _logger.exception("Create group error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------------------------- update
+    @http.route(
+        '/api/groups/<int:group_id>', type='http', auth='public',
+        methods=['PATCH', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def update_group(self, group_id, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            group = request.env['encoach.group'].sudo().browse(group_id)
+            if not group.exists():
+                return self._error_response('Group not found', 404)
+
+            body = self._get_json_body()
+            vals = {}
+            if 'name' in body:
+                vals['name'] = body['name']
+
+            if 'participants' in body:
+                vals['participant_ids'] = [(6, 0, [int(pid) for pid in body['participants']])]
+
+            if 'admins' in body:
+                vals['admin_ids'] = [(6, 0, [int(aid) for aid in body['admins']])]
+
+            if vals:
+                group.write(vals)
+
+            return self._json_response(self._serialize_group(group))
+        except Exception:
+            _logger.exception("Update group error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------------------------- delete
+    @http.route(
+        '/api/groups/<int:group_id>', type='http', auth='public',
+        methods=['DELETE', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def delete_group(self, group_id, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            group = request.env['encoach.group'].sudo().browse(group_id)
+            if not group.exists():
+                return self._error_response('Group not found', 404)
+
+            group.unlink()
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Delete group error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/discounts.py

@@ -0,0 +1,88 @@
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class DiscountsController(EncoachMixin, http.Controller):
+
+    @http.route('/api/discounts', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def list_discounts(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            discounts = request.env['encoach.discount'].sudo().search([])
+            return self._json_response([{
+                'id': d.id, 'code': d.code, 'percentage': d.percentage,
+                'expiryDate': d.expiry_date.isoformat() if d.expiry_date else None,
+                'maxUses': d.max_uses, 'uses': d.uses,
+            } for d in discounts])
+        except Exception:
+            _logger.exception("List discounts error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/discounts', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def create_discount(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            body = self._get_json_body()
+            code = body.get('code', '').strip()
+            if not code:
+                return self._error_response('code is required', 400)
+            discount = request.env['encoach.discount'].sudo().create({
+                'code': code,
+                'percentage': body.get('percentage', 0),
+                'expiry_date': body.get('expiryDate'),
+                'max_uses': body.get('maxUses', 0),
+            })
+            return self._json_response({
+                'id': discount.id, 'code': discount.code,
+                'percentage': discount.percentage,
+            })
+        except Exception:
+            _logger.exception("Create discount error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/discounts/<int:did>', type='http', auth='public', methods=['PATCH', 'OPTIONS'], csrf=False, cors='*')
+    def update_discount(self, did, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            discount = request.env['encoach.discount'].sudo().browse(did)
+            if not discount.exists():
+                return self._error_response('Discount not found', 404)
+            body = self._get_json_body()
+            vals = {}
+            if 'code' in body: vals['code'] = body['code']
+            if 'percentage' in body: vals['percentage'] = body['percentage']
+            if 'expiryDate' in body: vals['expiry_date'] = body['expiryDate']
+            if 'maxUses' in body: vals['max_uses'] = body['maxUses']
+            if vals:
+                discount.write(vals)
+            return self._json_response({'id': discount.id, 'code': discount.code})
+        except Exception:
+            _logger.exception("Update discount error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/discounts/<int:did>', type='http', auth='public', methods=['DELETE', 'OPTIONS'], csrf=False, cors='*')
+    def delete_discount(self, did, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            discount = request.env['encoach.discount'].sudo().browse(did)
+            if not discount.exists():
+                return self._error_response('Discount not found', 404)
+            discount.unlink()
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Delete discount error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/entities.py

@@ -0,0 +1,175 @@
+import json
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class EntitiesController(EncoachMixin, http.Controller):
+
+    @http.route('/api/entities', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def list_entities(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            offset, limit, page = self._paginate_params(kwargs)
+            entities = request.env['encoach.entity'].sudo().search([], limit=limit, offset=offset, order='name asc')
+            total = request.env['encoach.entity'].sudo().search_count([])
+            return self._json_response({
+                'items': [e.to_encoach_dict() for e in entities],
+                'total': total, 'page': page, 'limit': limit,
+            })
+        except Exception:
+            _logger.exception("List entities error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/entities', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def create_entity(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            body = self._get_json_body()
+            name = body.get('name', '').strip()
+            if not name:
+                return self._error_response('name is required', 400)
+            entity = request.env['encoach.entity'].sudo().create({
+                'name': name,
+                'label': body.get('label', name),
+                'licenses': body.get('licenses', 0),
+                'expiry_date': body.get('expiryDate'),
+                'payment_currency': body.get('paymentCurrency'),
+                'payment_price': body.get('paymentPrice', 0),
+            })
+            return self._json_response(entity.to_encoach_dict())
+        except Exception:
+            _logger.exception("Create entity error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/entities/<int:entity_id>', type='http', auth='public', methods=['PATCH', 'OPTIONS'], csrf=False, cors='*')
+    def update_entity(self, entity_id, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            entity = request.env['encoach.entity'].sudo().browse(entity_id)
+            if not entity.exists():
+                return self._error_response('Entity not found', 404)
+            body = self._get_json_body()
+            vals = {}
+            if 'name' in body: vals['name'] = body['name']
+            if 'label' in body: vals['label'] = body['label']
+            if 'licenses' in body: vals['licenses'] = body['licenses']
+            if 'expiryDate' in body: vals['expiry_date'] = body['expiryDate']
+            if 'paymentCurrency' in body: vals['payment_currency'] = body['paymentCurrency']
+            if 'paymentPrice' in body: vals['payment_price'] = body['paymentPrice']
+            if vals:
+                entity.write(vals)
+            return self._json_response(entity.to_encoach_dict())
+        except Exception:
+            _logger.exception("Update entity error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/entities/<int:entity_id>', type='http', auth='public', methods=['DELETE', 'OPTIONS'], csrf=False, cors='*')
+    def delete_entity(self, entity_id, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            entity = request.env['encoach.entity'].sudo().browse(entity_id)
+            if not entity.exists():
+                return self._error_response('Entity not found', 404)
+            entity.unlink()
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Delete entity error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/roles', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def list_roles(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            domain = []
+            entity_id = kwargs.get('entityID')
+            if entity_id:
+                domain.append(('entity_id', '=', int(entity_id)))
+            roles = request.env['encoach.role'].sudo().search(domain)
+            return self._json_response([{
+                'id': r.id, 'name': r.name,
+                'entityId': r.entity_id.id if r.entity_id else None,
+            } for r in roles])
+        except Exception:
+            _logger.exception("List roles error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/roles', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def create_role(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            body = self._get_json_body()
+            name = body.get('name', '').strip()
+            if not name:
+                return self._error_response('name is required', 400)
+            vals = {'name': name}
+            if body.get('entityId'):
+                vals['entity_id'] = int(body['entityId'])
+            role = request.env['encoach.role'].sudo().create(vals)
+            return self._json_response({'id': role.id, 'name': role.name, 'entityId': role.entity_id.id if role.entity_id else None})
+        except Exception:
+            _logger.exception("Create role error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/roles/<int:role_id>', type='http', auth='public', methods=['PATCH', 'OPTIONS'], csrf=False, cors='*')
+    def update_role(self, role_id, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            role = request.env['encoach.role'].sudo().browse(role_id)
+            if not role.exists():
+                return self._error_response('Role not found', 404)
+            body = self._get_json_body()
+            vals = {}
+            if 'name' in body: vals['name'] = body['name']
+            if vals:
+                role.write(vals)
+            return self._json_response({'id': role.id, 'name': role.name, 'entityId': role.entity_id.id if role.entity_id else None})
+        except Exception:
+            _logger.exception("Update role error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/roles/<int:role_id>', type='http', auth='public', methods=['DELETE', 'OPTIONS'], csrf=False, cors='*')
+    def delete_role(self, role_id, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            role = request.env['encoach.role'].sudo().browse(role_id)
+            if not role.exists():
+                return self._error_response('Role not found', 404)
+            role.unlink()
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Delete role error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/permissions', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def list_permissions(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            perms = request.env['encoach.permission'].sudo().search([])
+            return self._json_response([{'id': p.id, 'topic': p.topic, 'type': p.perm_type} for p in perms])
+        except Exception:
+            _logger.exception("List permissions error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/evaluations.py

@@ -0,0 +1,293 @@
+import json
+import logging
+import threading
+
+import odoo
+from odoo import api, SUPERUSER_ID, http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+def _run_grading_background(dbname, evaluation_id, input_data, grading_type):
+    """Execute AI grading in a background thread with its own cursor."""
+    try:
+        registry = odoo.registry(dbname)
+        with registry.cursor() as cr:
+            env = api.Environment(cr, SUPERUSER_ID, {})
+            service = env['encoach.ai.grading']
+            if grading_type == 'writing':
+                service.grade_writing(evaluation_id, input_data)
+            elif grading_type == 'speaking':
+                service.grade_speaking(evaluation_id, input_data)
+            elif grading_type == 'interactive_speaking':
+                service.grade_interactive_speaking(evaluation_id, input_data)
+    except Exception:
+        _logger.exception("Background grading failed for evaluation %s", evaluation_id)
+        try:
+            registry = odoo.registry(dbname)
+            with registry.cursor() as cr:
+                env = api.Environment(cr, SUPERUSER_ID, {})
+                env['encoach.evaluation'].browse(evaluation_id).write({
+                    'status': 'error',
+                    'error_message': 'Grading failed unexpectedly',
+                })
+        except Exception:
+            _logger.exception("Failed to update evaluation status after error")
+
+
+class EvaluationsController(EncoachMixin, http.Controller):
+
+    # ------------------------------------------------- evaluate writing
+    @http.route('/api/evaluate/writing', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def evaluate_writing(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            required = ('sessionId', 'exerciseId', 'question', 'answer', 'task')
+            for field in required:
+                if not body.get(field):
+                    return self._error_response(f'{field} is required', 400)
+
+            Evaluation = request.env['encoach.evaluation'].sudo()
+            evaluation = Evaluation.create({
+                'user_id': int(body.get('userId', user.id)),
+                'session_id': int(body['sessionId']),
+                'exercise_id': body['exerciseId'],
+                'eval_type': 'writing',
+                'status': 'pending',
+                'input_data': json.dumps({
+                    'question': body['question'],
+                    'answer': body['answer'],
+                    'task': body['task'],
+                    'attachment': body.get('attachment'),
+                }),
+            })
+
+            dbname = request.env.cr.dbname
+            input_data = {
+                'question': body['question'],
+                'answer': body['answer'],
+                'task': body['task'],
+                'attachment': body.get('attachment'),
+            }
+            thread = threading.Thread(
+                target=_run_grading_background,
+                args=(dbname, evaluation.id, input_data, 'writing'),
+                daemon=True,
+            )
+            thread.start()
+
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Evaluate writing error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------- evaluate speaking
+    @http.route('/api/evaluate/speaking', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def evaluate_speaking(self, **kwargs):
+        """Accept multipart form with audio files and question fields."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            form = request.httprequest.form
+            files = request.httprequest.files
+
+            user_id = form.get('userId', str(user.id))
+            session_id = form.get('sessionId')
+            exercise_id = form.get('exerciseId')
+            task = form.get('task')
+
+            if not session_id or not exercise_id or not task:
+                return self._error_response('sessionId, exerciseId, and task are required', 400)
+
+            audio_entries = []
+            idx = 1
+            while True:
+                audio_key = f'audio_{idx}'
+                question_key = f'question_{idx}'
+                audio_file = files.get(audio_key)
+                if not audio_file:
+                    break
+                audio_entries.append({
+                    'audio_data': audio_file.read(),
+                    'audio_filename': audio_file.filename,
+                    'question': form.get(question_key, ''),
+                })
+                idx += 1
+
+            if not audio_entries:
+                return self._error_response('At least one audio file is required', 400)
+
+            Attachment = request.env['ir.attachment'].sudo()
+            saved_audios = []
+            for entry in audio_entries:
+                import base64
+                att = Attachment.create({
+                    'name': entry['audio_filename'],
+                    'datas': base64.b64encode(entry['audio_data']),
+                    'res_model': 'encoach.evaluation',
+                    'type': 'binary',
+                })
+                saved_audios.append({
+                    'attachment_id': att.id,
+                    'question': entry['question'],
+                })
+
+            Evaluation = request.env['encoach.evaluation'].sudo()
+            evaluation = Evaluation.create({
+                'user_id': int(user_id),
+                'session_id': int(session_id),
+                'exercise_id': exercise_id,
+                'eval_type': 'speaking',
+                'status': 'pending',
+                'input_data': json.dumps({
+                    'task': task,
+                    'audios': [{'attachment_id': a['attachment_id'], 'question': a['question']} for a in saved_audios],
+                }),
+            })
+
+            dbname = request.env.cr.dbname
+            input_data = {
+                'task': task,
+                'audios': saved_audios,
+            }
+            thread = threading.Thread(
+                target=_run_grading_background,
+                args=(dbname, evaluation.id, input_data, 'speaking'),
+                daemon=True,
+            )
+            thread.start()
+
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Evaluate speaking error")
+            return self._error_response('Internal server error', 500)
+
+    # ---------------------------------------- evaluate interactive speaking
+    @http.route(
+        '/api/evaluate/interactiveSpeaking', type='http', auth='public',
+        methods=['POST', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def evaluate_interactive_speaking(self, **kwargs):
+        """Same as speaking but for interactive Q&A pairs."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            form = request.httprequest.form
+            files = request.httprequest.files
+
+            user_id = form.get('userId', str(user.id))
+            session_id = form.get('sessionId')
+            exercise_id = form.get('exerciseId')
+            task = form.get('task')
+
+            if not session_id or not exercise_id or not task:
+                return self._error_response('sessionId, exerciseId, and task are required', 400)
+
+            audio_entries = []
+            idx = 1
+            while True:
+                audio_key = f'audio_{idx}'
+                question_key = f'question_{idx}'
+                audio_file = files.get(audio_key)
+                if not audio_file:
+                    break
+                audio_entries.append({
+                    'audio_data': audio_file.read(),
+                    'audio_filename': audio_file.filename,
+                    'question': form.get(question_key, ''),
+                })
+                idx += 1
+
+            if not audio_entries:
+                return self._error_response('At least one audio file is required', 400)
+
+            import base64
+            Attachment = request.env['ir.attachment'].sudo()
+            saved_audios = []
+            for entry in audio_entries:
+                att = Attachment.create({
+                    'name': entry['audio_filename'],
+                    'datas': base64.b64encode(entry['audio_data']),
+                    'res_model': 'encoach.evaluation',
+                    'type': 'binary',
+                })
+                saved_audios.append({
+                    'attachment_id': att.id,
+                    'question': entry['question'],
+                })
+
+            Evaluation = request.env['encoach.evaluation'].sudo()
+            evaluation = Evaluation.create({
+                'user_id': int(user_id),
+                'session_id': int(session_id),
+                'exercise_id': exercise_id,
+                'eval_type': 'interactive_speaking',
+                'status': 'pending',
+                'input_data': json.dumps({
+                    'task': task,
+                    'audios': [{'attachment_id': a['attachment_id'], 'question': a['question']} for a in saved_audios],
+                }),
+            })
+
+            dbname = request.env.cr.dbname
+            input_data = {
+                'task': task,
+                'audios': saved_audios,
+            }
+            thread = threading.Thread(
+                target=_run_grading_background,
+                args=(dbname, evaluation.id, input_data, 'interactive_speaking'),
+                daemon=True,
+            )
+            thread.start()
+
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Evaluate interactive speaking error")
+            return self._error_response('Internal server error', 500)
+
+    # ----------------------------------------------------- poll status
+    @http.route(['/api/evaluate/<int:session_id>/<string:exercise_id>', '/api/evaluate/status'], type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def evaluation_status(self, session_id=None, exercise_id=None, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            if not session_id:
+                session_id = kwargs.get('sessionId')
+            if not exercise_id:
+                exercise_id = kwargs.get('exerciseId')
+            if not session_id or not exercise_id:
+                return self._error_response('sessionId and exerciseId are required', 400)
+
+            evaluation = request.env['encoach.evaluation'].sudo().search([
+                ('session_id', '=', int(session_id)),
+                ('exercise_id', '=', str(exercise_id)),
+            ], limit=1, order='create_date desc')
+
+            if not evaluation:
+                return self._error_response('Evaluation not found', 404)
+
+            result = None
+            if evaluation.status == 'completed' and evaluation.result:
+                result = json.loads(evaluation.result)
+
+            return self._json_response({
+                'status': evaluation.status,
+                'result': result,
+            })
+        except Exception:
+            _logger.exception("Evaluation status error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/exams.py

@@ -0,0 +1,220 @@
+import json
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+VALID_MODULES = ('reading', 'listening', 'writing', 'speaking', 'level')
+
+
+class ExamsController(EncoachMixin, http.Controller):
+
+    # --------------------------------------------------------------- list
+    @http.route('/api/exam', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def list_exams(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            domain = []
+            module = kwargs.get('module')
+            if module and module in VALID_MODULES:
+                domain.append(('module', '=', module))
+
+            creator = kwargs.get('createdBy')
+            if creator:
+                domain.append(('create_uid', '=', int(creator)))
+
+            is_published = kwargs.get('isPublished')
+            if is_published is not None:
+                domain.append(('is_published', '=', is_published in ('true', '1', True)))
+
+            entity_id = kwargs.get('entityID')
+            if entity_id:
+                domain.append(('entity_id', '=', int(entity_id)))
+
+            offset, limit, page = self._paginate_params(kwargs)
+            Exam = request.env['encoach.exam'].sudo()
+            total = Exam.search_count(domain)
+            exams = Exam.search(domain, offset=offset, limit=limit, order='create_date desc')
+
+            return self._json_response({
+                'exams': [self._serialize_exam(e) for e in exams],
+                'total': total,
+                'page': page,
+                'limit': limit,
+            })
+        except Exception:
+            _logger.exception("List exams error")
+            return self._error_response('Internal server error', 500)
+
+    # --------------------------------------------------------------- create
+    @http.route(
+        '/api/exam/<string:module>', type='http', auth='public',
+        methods=['POST', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def create_exam(self, module, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            if module not in VALID_MODULES:
+                return self._error_response(f'Invalid module: {module}', 400)
+
+            body = self._get_json_body()
+            vals = {
+                'name': body.get('name', ''),
+                'module': module,
+                'create_uid': user.id,
+            }
+            if 'parts' in body:
+                vals['parts'] = json.dumps(body['parts']) if isinstance(body['parts'], (list, dict)) else body['parts']
+            if 'difficulty' in body:
+                vals['difficulty'] = body['difficulty']
+            if 'tags' in body:
+                vals['tags'] = json.dumps(body['tags']) if isinstance(body['tags'], list) else body['tags']
+            if 'isPublished' in body:
+                vals['is_published'] = body['isPublished']
+            if 'entityID' in body and body['entityID']:
+                vals['entity_id'] = int(body['entityID'])
+
+            exam = request.env['encoach.exam'].sudo().with_user(user).create(vals)
+            return self._json_response(self._serialize_exam(exam), status=201)
+        except Exception:
+            _logger.exception("Create exam error")
+            return self._error_response('Internal server error', 500)
+
+    # ----------------------------------------------------------- get by id
+    @http.route(
+        '/api/exam/<string:module>/<int:exam_id>', type='http', auth='public',
+        methods=['GET', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def get_exam(self, module, exam_id, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            exam = request.env['encoach.exam'].sudo().browse(exam_id)
+            if not exam.exists():
+                return self._error_response('Exam not found', 404)
+
+            return self._json_response(self._serialize_exam(exam))
+        except Exception:
+            _logger.exception("Get exam error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------------------------- update
+    @http.route(
+        '/api/exam/<string:module>/<int:exam_id>', type='http', auth='public',
+        methods=['PATCH', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def update_exam(self, module, exam_id, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            exam = request.env['encoach.exam'].sudo().browse(exam_id)
+            if not exam.exists():
+                return self._error_response('Exam not found', 404)
+
+            body = self._get_json_body()
+            vals = {}
+            if 'name' in body:
+                vals['name'] = body['name']
+            if 'parts' in body:
+                vals['parts'] = json.dumps(body['parts']) if isinstance(body['parts'], (list, dict)) else body['parts']
+            if 'difficulty' in body:
+                vals['difficulty'] = body['difficulty']
+            if 'tags' in body:
+                vals['tags'] = json.dumps(body['tags']) if isinstance(body['tags'], list) else body['tags']
+            if 'isPublished' in body:
+                vals['is_published'] = body['isPublished']
+
+            if vals:
+                exam.write(vals)
+
+            return self._json_response(self._serialize_exam(exam))
+        except Exception:
+            _logger.exception("Update exam error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------------------------- delete
+    @http.route(
+        '/api/exam/<string:module>/<int:exam_id>', type='http', auth='public',
+        methods=['DELETE', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def delete_exam(self, module, exam_id, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            exam = request.env['encoach.exam'].sudo().browse(exam_id)
+            if not exam.exists():
+                return self._error_response('Exam not found', 404)
+
+            exam.unlink()
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Delete exam error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------------------------- import
+    @http.route(
+        '/api/exam/<string:module>/import/', type='http', auth='public',
+        methods=['POST', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def import_exam(self, module, **kwargs):
+        """Import an exam from an uploaded file (Word/Excel)."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            if module not in VALID_MODULES:
+                return self._error_response(f'Invalid module: {module}', 400)
+
+            exercises_file = request.httprequest.files.get('exercises')
+            solutions_file = request.httprequest.files.get('solutions')
+            if not exercises_file:
+                return self._error_response('exercises file is required', 400)
+
+            Exam = request.env['encoach.exam'].sudo()
+            result = Exam.import_from_file(
+                module=module,
+                exercises_data=exercises_file.read(),
+                exercises_filename=exercises_file.filename,
+                solutions_data=solutions_file.read() if solutions_file else None,
+                solutions_filename=solutions_file.filename if solutions_file else None,
+                user=user,
+            )
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Import exam error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------------------ avatars
+    @http.route('/api/exam/avatars', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def list_avatars(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            avatars = request.env['encoach.elai.avatar'].sudo().search([])
+            data = [{
+                'name': a.name,
+                'avatar_code': a.avatar_code,
+                'avatar_url': a.avatar_url or '',
+                'gender': a.gender or '',
+            } for a in avatars]
+            return self._json_response(data)
+        except Exception:
+            _logger.exception("List avatars error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/generation.py

@@ -0,0 +1,347 @@
+import json
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class GenerationController(EncoachMixin, http.Controller):
+
+    # ------------------------------------------------- reading passage
+    @http.route(
+        '/api/exam/reading/<int:passage>', type='http', auth='public',
+        methods=['GET', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def generate_reading_passage(self, passage, **kwargs):
+        """Generate a reading passage (1, 2, or 3) using GPT-4o."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            if passage not in (1, 2, 3):
+                return self._error_response('passage must be 1, 2, or 3', 400)
+
+            topic = kwargs.get('topic')
+            word_count = int(kwargs.get('word_count', 500))
+
+            GenService = request.env['encoach.ai.generation'].sudo()
+            result = GenService.generate_reading_passage(
+                passage=passage,
+                topic=topic,
+                word_count=word_count,
+            )
+
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Generate reading passage error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------ reading exercises
+    @http.route('/api/exam/reading/', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def generate_reading_exercises(self, **kwargs):
+        """Generate reading exercises from a passage."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            text = body.get('text', '')
+            exercises = body.get('exercises', [])
+            difficulty = body.get('difficulty', ['B1', 'B2'])
+
+            if not text or not exercises:
+                return self._error_response('text and exercises are required', 400)
+
+            GenService = request.env['encoach.ai.generation'].sudo()
+            result = GenService.generate_reading_exercises(
+                text=text,
+                exercises=exercises,
+                difficulty=difficulty,
+            )
+
+            return self._json_response({'exercises': result})
+        except Exception:
+            _logger.exception("Generate reading exercises error")
+            return self._error_response('Internal server error', 500)
+
+    # ----------------------------------------------- listening dialog
+    @http.route(
+        '/api/exam/listening/<int:section>', type='http', auth='public',
+        methods=['GET', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def generate_listening_dialog(self, section, **kwargs):
+        """Generate a listening dialog/monologue (section 1-4) using GPT-4o."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            if section not in (1, 2, 3, 4):
+                return self._error_response('section must be 1, 2, 3, or 4', 400)
+
+            topic = kwargs.get('topic')
+            difficulty = kwargs.get('difficulty')
+
+            GenService = request.env['encoach.ai.generation'].sudo()
+            result = GenService.generate_listening_dialog(
+                section=section,
+                topic=topic,
+                difficulty=difficulty,
+            )
+
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Generate listening dialog error")
+            return self._error_response('Internal server error', 500)
+
+    # ---------------------------------------- listening exercises
+    @http.route('/api/exam/listening/', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def generate_listening_exercises(self, **kwargs):
+        """Generate listening exercises from a dialog transcript."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            text = body.get('text', '')
+            exercises = body.get('exercises', [])
+            difficulty = body.get('difficulty', ['B1'])
+
+            if not text or not exercises:
+                return self._error_response('text and exercises are required', 400)
+
+            GenService = request.env['encoach.ai.generation'].sudo()
+            result = GenService.generate_listening_exercises(
+                text=text,
+                exercises=exercises,
+                difficulty=difficulty,
+            )
+
+            return self._json_response({'exercises': result})
+        except Exception:
+            _logger.exception("Generate listening exercises error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------- writing task
+    @http.route(
+        '/api/exam/writing/<int:task>', type='http', auth='public',
+        methods=['GET', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def generate_writing_task(self, task, **kwargs):
+        """Generate a writing task prompt (task 1 or 2) using GPT-4o."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            if task not in (1, 2):
+                return self._error_response('task must be 1 or 2', 400)
+
+            topic = kwargs.get('topic')
+            difficulty = kwargs.get('difficulty')
+
+            GenService = request.env['encoach.ai.generation'].sudo()
+            result = GenService.generate_writing_task(
+                task=task,
+                topic=topic,
+                difficulty=difficulty,
+            )
+
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Generate writing task error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------ speaking task
+    @http.route(
+        '/api/exam/speaking/<int:task>', type='http', auth='public',
+        methods=['GET', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def generate_speaking_task(self, task, **kwargs):
+        """Generate a speaking task prompt (part 1, 2, or 3) using GPT-4o."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            if task not in (1, 2, 3):
+                return self._error_response('task must be 1, 2, or 3', 400)
+
+            topic = kwargs.get('topic')
+            first_topic = kwargs.get('first_topic')
+            second_topic = kwargs.get('second_topic')
+            difficulty = kwargs.get('difficulty')
+
+            GenService = request.env['encoach.ai.generation'].sudo()
+            result = GenService.generate_speaking_task(
+                task=task,
+                topic=topic,
+                first_topic=first_topic,
+                second_topic=second_topic,
+                difficulty=difficulty,
+            )
+
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Generate speaking task error")
+            return self._error_response('Internal server error', 500)
+
+    # --------------------------------------------- level exercises
+    @http.route('/api/exam/level/', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def generate_level_exercises(self, **kwargs):
+        """Generate level-test exercises using GPT-4o."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            exercises = body.get('exercises', [])
+            difficulty = body.get('difficulty', ['B1'])
+
+            if not exercises:
+                return self._error_response('exercises specification is required', 400)
+
+            GenService = request.env['encoach.ai.generation'].sudo()
+            result = GenService.generate_level_exercises(
+                exercises=exercises,
+                difficulty=difficulty,
+            )
+
+            return self._json_response({'exercises': result})
+        except Exception:
+            _logger.exception("Generate level exercises error")
+            return self._error_response('Internal server error', 500)
+
+    # --------------------------------------------- writing attachment (vision)
+    @http.route(
+        '/api/exam/writing/<int:task>/attachment', type='http', auth='public',
+        methods=['POST', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def generate_writing_attachment(self, task, **kwargs):
+        """Academic writing Task 1 with image upload for GPT-4o vision."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            if task not in (1, 2):
+                return self._error_response('task must be 1 or 2', 400)
+
+            files = request.httprequest.files
+            form = request.httprequest.form
+            image_file = files.get('file')
+            difficulty = form.get('difficulty', 'B2')
+
+            if not image_file:
+                return self._error_response('file (image) is required', 400)
+
+            import base64
+            image_data = base64.b64encode(image_file.read()).decode('utf-8')
+            mime_type = image_file.content_type or 'image/png'
+
+            GenService = request.env['encoach.ai.generation'].sudo()
+            result = GenService.generate_writing_with_image(
+                task=task,
+                image_b64=image_data,
+                mime_type=mime_type,
+                difficulty=difficulty,
+            )
+
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Generate writing attachment error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------- pre-built level exam
+    @http.route('/api/exam/level/', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def get_level_exam(self, **kwargs):
+        """Return a pre-built level exam (no AI generation)."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            exams = request.env['encoach.exam'].sudo().search([
+                ('module', '=', 'level'),
+                ('access', '=', 'public'),
+            ], limit=1, order='create_date desc')
+            if not exams:
+                return self._error_response('No level exam found', 404)
+            return self._json_response(exams[0].to_encoach_dict())
+        except Exception:
+            _logger.exception("Get level exam error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------- UTAS level exam
+    @http.route('/api/exam/level/utas', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def get_utas_level_exam(self, **kwargs):
+        """Return a UTAS-format level exam."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            exams = request.env['encoach.exam'].sudo().search([
+                ('module', '=', 'level'),
+                ('label', 'ilike', 'utas'),
+            ], limit=1, order='create_date desc')
+            if not exams:
+                return self._error_response('No UTAS level exam found', 404)
+            return self._json_response(exams[0].to_encoach_dict())
+        except Exception:
+            _logger.exception("Get UTAS level exam error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------- level exam import
+    @http.route('/api/exam/level/import/', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def import_level_exam(self, **kwargs):
+        """Import level exam from uploaded file."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            files = request.httprequest.files
+            exercises_file = files.get('exercises')
+            if not exercises_file:
+                return self._error_response('exercises file is required', 400)
+
+            import json as _json
+            content = exercises_file.read().decode('utf-8')
+            data = _json.loads(content)
+
+            exam = request.env['encoach.exam'].sudo().create({
+                'module': 'level',
+                'label': data.get('label', 'Imported Level Exam'),
+                'parts': data.get('parts', []),
+                'access': 'private',
+            })
+            return self._json_response(exam.to_encoach_dict())
+        except Exception:
+            _logger.exception("Import level exam error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------- custom level exam
+    @http.route('/api/exam/level/custom/', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def generate_custom_level(self, **kwargs):
+        """Generate custom level exam from JSON specification."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            spec = body.get('spec', body)
+
+            GenService = request.env['encoach.ai.generation'].sudo()
+            result = GenService.generate_level_exercises(
+                exercises=spec.get('exercises', []),
+                difficulty=spec.get('difficulty', ['B1', 'B2']),
+            )
+            return self._json_response({'exercises': result})
+        except Exception:
+            _logger.exception("Generate custom level error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/grading.py

@@ -0,0 +1,65 @@
+import json
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class GradingController(EncoachMixin, http.Controller):
+
+    # ------------------------------------------------- grade multiple
+    @http.route('/api/grading/multiple', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def grade_multiple(self, **kwargs):
+        """Grade multiple short-answer exercises using GPT-4o."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            text = body.get('text', '')
+            questions = body.get('questions', [])
+            answers = body.get('answers', [])
+
+            if not questions or not answers:
+                return self._error_response('questions and answers are required', 400)
+            if len(questions) != len(answers):
+                return self._error_response('questions and answers must have the same length', 400)
+
+            GradingService = request.env['encoach.ai.grading'].sudo()
+            result = GradingService.grade_short_answers(
+                text=text,
+                questions=questions,
+                answers=answers,
+            )
+
+            return self._json_response({'exercises': result})
+        except Exception:
+            _logger.exception("Grade multiple error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------ grading summary
+    @http.route('/api/exam/grade/summary', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def grading_summary(self, **kwargs):
+        """Generate a grading summary for a full exam session."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            sections = body.get('sections', [])
+            if not sections:
+                return self._error_response('sections array is required', 400)
+
+            GradingService = request.env['encoach.ai.grading'].sudo()
+            result = GradingService.generate_grading_summary(sections=sections)
+
+            return self._json_response({'sections': result})
+        except Exception:
+            _logger.exception("Grading summary error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/media.py

@@ -0,0 +1,213 @@
+import base64
+import json
+import logging
+
+from odoo import http
+from odoo.http import request, Response
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class MediaController(EncoachMixin, http.Controller):
+
+    # ------------------------------------------- listening MP3
+    @http.route(
+        '/api/exam/listening/media', type='http', auth='public',
+        methods=['POST', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def generate_listening_mp3(self, **kwargs):
+        """Generate listening MP3 audio from a dialog/monologue via AWS Polly."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            conversation = body.get('conversation')
+            monologue = body.get('monologue')
+
+            if not conversation and not monologue:
+                return self._error_response('conversation or monologue is required', 400)
+
+            MediaService = request.env['encoach.ai.media'].sudo()
+            mp3_data = MediaService.generate_listening_audio(
+                conversation=conversation,
+                monologue=monologue,
+            )
+
+            return Response(
+                mp3_data,
+                status=200,
+                content_type='audio/mpeg',
+                headers={
+                    'Access-Control-Allow-Origin': '*',
+                    'Content-Disposition': 'attachment; filename="listening.mp3"',
+                },
+            )
+        except Exception:
+            _logger.exception("Generate listening MP3 error")
+            return self._error_response('Internal server error', 500)
+
+    # ---------------------------------------- transcribe audio
+    @http.route(
+        '/api/exam/listening/transcribe', type='http', auth='public',
+        methods=['POST', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def transcribe_listening(self, **kwargs):
+        """Transcribe audio using Whisper and return dialog object."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            audio_file = request.httprequest.files.get('audio')
+            if not audio_file:
+                return self._error_response('audio file is required', 400)
+
+            audio_data = audio_file.read()
+            MediaService = request.env['encoach.ai.media'].sudo()
+            result = MediaService.transcribe_to_dialog(
+                audio_data=audio_data,
+                filename=audio_file.filename,
+            )
+
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Transcribe listening error")
+            return self._error_response('Internal server error', 500)
+
+    # --------------------------------- listening instructions MP3
+    @http.route(
+        '/api/exam/listening/instructions', type='http', auth='public',
+        methods=['POST', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def generate_instructions_mp3(self, **kwargs):
+        """Generate MP3 for listening instructions text via AWS Polly."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            text = body.get('text', '')
+            if not text:
+                return self._error_response('text is required', 400)
+
+            MediaService = request.env['encoach.ai.media'].sudo()
+            mp3_data = MediaService.generate_instructions_audio(text=text)
+
+            return Response(
+                mp3_data,
+                status=200,
+                content_type='audio/mpeg',
+                headers={
+                    'Access-Control-Allow-Origin': '*',
+                    'Content-Disposition': 'attachment; filename="instructions.mp3"',
+                },
+            )
+        except Exception:
+            _logger.exception("Generate instructions MP3 error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------ speaking video
+    @http.route(
+        '/api/exam/speaking/media', type='http', auth='public',
+        methods=['POST', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def generate_speaking_video(self, **kwargs):
+        """Start AI avatar video generation via ELAI (async)."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            text = body.get('text', '')
+            avatar = body.get('avatar', '')
+            if not text:
+                return self._error_response('text is required', 400)
+
+            MediaService = request.env['encoach.ai.media'].sudo()
+            result = MediaService.create_speaking_video(
+                text=text,
+                avatar_code=avatar,
+            )
+
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Generate speaking video error")
+            return self._error_response('Internal server error', 500)
+
+    # --------------------------------- poll speaking video status
+    @http.route(
+        '/api/exam/speaking/media/<string:vid_id>', type='http', auth='public',
+        methods=['GET', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def poll_speaking_video(self, vid_id, **kwargs):
+        """Poll ELAI video generation status."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            MediaService = request.env['encoach.ai.media'].sudo()
+            result = MediaService.poll_video_status(video_id=vid_id)
+
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Poll speaking video error")
+            return self._error_response('Internal server error', 500)
+
+    # ----------------------------------------- speaking avatars
+    @http.route(
+        '/api/exam/speaking/avatars', type='http', auth='public',
+        methods=['GET', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def list_speaking_avatars(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            avatars = request.env['encoach.elai.avatar'].sudo().search([])
+            data = [{
+                'name': a.name,
+                'avatar_code': a.avatar_code,
+                'avatar_url': a.avatar_url or '',
+                'gender': a.gender or '',
+                'canvas': getattr(a, 'canvas', '') or '',
+                'voice_id': getattr(a, 'voice_id', '') or '',
+                'voice_provider': getattr(a, 'voice_provider', '') or '',
+            } for a in avatars]
+
+            return self._json_response(data)
+        except Exception:
+            _logger.exception("List speaking avatars error")
+            return self._error_response('Internal server error', 500)
+
+    # ---------------------------------------- general transcribe
+    @http.route('/api/transcribe', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def transcribe(self, **kwargs):
+        """Transcribe an audio file using Whisper."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            audio_file = request.httprequest.files.get('audio') or request.httprequest.files.get('file')
+            if not audio_file:
+                return self._error_response('audio file is required', 400)
+
+            audio_data = audio_file.read()
+            MediaService = request.env['encoach.ai.media'].sudo()
+            result = MediaService.transcribe_audio(
+                audio_data=audio_data,
+                filename=audio_file.filename,
+            )
+
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Transcribe error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/registration.py

@@ -0,0 +1,149 @@
+import logging
+from datetime import datetime, timedelta
+
+import jwt as pyjwt
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class RegistrationController(EncoachMixin, http.Controller):
+
+    @http.route('/api/register', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def register(self, **kwargs):
+        try:
+            body = self._get_json_body()
+            email = body.get('email', '').strip()
+            password = body.get('password', '')
+            name = body.get('name', '').strip()
+            user_type = body.get('type', 'student')
+
+            if not email or not password or not name:
+                return self._error_response('name, email, and password are required', 400)
+
+            Users = request.env['res.users'].sudo()
+            existing = Users.search([('login', '=', email)], limit=1)
+            if existing:
+                return self._error_response('A user with this email already exists', 409)
+
+            main_company = request.env['res.company'].sudo().search([], limit=1, order='id')
+            vals = {
+                'name': name,
+                'login': email,
+                'password': password,
+                'encoach_type': user_type,
+                'is_verified': False,
+                'company_id': main_company.id,
+                'company_ids': [(6, 0, [main_company.id])],
+            }
+
+            code_str = body.get('code')
+            if code_str:
+                result = request.env['encoach.code'].sudo().validate_code(code_str)
+                if result.get('valid'):
+                    code_rec = request.env['encoach.code'].sudo().search([('code', '=', code_str)], limit=1)
+                    if code_rec and code_rec.user_type:
+                        vals['encoach_type'] = code_rec.user_type
+
+            user = Users.create(vals)
+
+            if code_str:
+                code_rec = request.env['encoach.code'].sudo().search([('code', '=', code_str)], limit=1)
+                if code_rec:
+                    if code_rec.entity_id:
+                        request.env['encoach.user.entity.rel'].sudo().create({
+                            'user_id': user.id,
+                            'entity_id': code_rec.entity_id.id,
+                        })
+                    code_rec.sudo().write({'uses': code_rec.uses + 1})
+
+            secret = request.env['ir.config_parameter'].sudo().get_param('encoach.jwt_secret')
+            token = pyjwt.encode({
+                'user_id': user.id,
+                'email': user.login,
+                'iat': datetime.utcnow(),
+                'exp': datetime.utcnow() + timedelta(hours=72),
+            }, secret, algorithm='HS256')
+
+            return self._json_response({
+                'user': self._serialize(user),
+                'token': token,
+            }, status=201)
+        except Exception:
+            _logger.exception("Registration error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route(
+        '/api/code/<string:code>', type='http', auth='public',
+        methods=['GET', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def validate_code(self, code, **kwargs):
+        try:
+            result = request.env['encoach.code'].sudo().validate_code(code)
+            if not result.get('valid'):
+                return self._error_response(result.get('error', 'Invalid code'), 404)
+            return self._json_response(result['code'])
+        except Exception:
+            _logger.exception("Validate code error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/batch_users', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def batch_users(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            users_data = body.get('users', [])
+            if not users_data:
+                return self._error_response('users array is required', 400)
+
+            mixin = request.env['encoach.registration.mixin'].sudo()
+            result = mixin.batch_import(users_data, user.id)
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Batch users error")
+            return self._error_response('Internal server error', 500)
+
+    @http.route('/api/make_user', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def make_user(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            email = body.get('email', '').strip()
+            name = body.get('name', '').strip()
+            password = body.get('password', '')
+            if not email or not name:
+                return self._error_response('name and email are required', 400)
+
+            Users = request.env['res.users'].sudo()
+            existing = Users.search([('login', '=', email)], limit=1)
+            if existing:
+                return self._error_response('A user with this email already exists', 409)
+
+            import secrets
+            if not password:
+                password = secrets.token_urlsafe(12)
+
+            new_user = Users.create({
+                'name': name,
+                'login': email,
+                'password': password,
+                'encoach_type': body.get('type', 'student'),
+                'is_verified': body.get('isVerified', True),
+            })
+
+            result = self._serialize(new_user)
+            result['tempPassword'] = password
+            return self._json_response(result, status=201)
+        except Exception:
+            _logger.exception("Make user error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/sessions.py

@@ -0,0 +1,73 @@
+import json
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class SessionsController(EncoachMixin, http.Controller):
+
+    # -------------------------------------------------------------- save
+    @http.route('/api/sessions', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def save_session(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+
+            session_id = body.get('_id') or body.get('id')
+            Session = request.env['encoach.session'].sudo()
+
+            vals = {}
+            if body.get('examId'):
+                vals['exam_id'] = int(body['examId'])
+            if body.get('module'):
+                vals['module'] = body['module']
+            if body.get('answers') is not None:
+                vals['answers'] = json.dumps(body['answers']) if isinstance(body['answers'], dict) else body['answers']
+            if body.get('startedAt'):
+                vals['started_at'] = body['startedAt']
+            if body.get('completedAt'):
+                vals['completed_at'] = body['completedAt']
+            if body.get('assignmentId'):
+                vals['assignment_id'] = int(body['assignmentId'])
+
+            if session_id:
+                record = Session.browse(int(session_id))
+                if record.exists():
+                    record.write(vals)
+                    return self._json_response(self._serialize_session(record))
+
+            vals['user_id'] = user.id
+            record = Session.create(vals)
+            return self._json_response(self._serialize_session(record), status=201)
+        except Exception:
+            _logger.exception("Save session error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------------------- delete
+    @http.route(
+        '/api/sessions/<int:sid>', type='http', auth='public',
+        methods=['DELETE', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def delete_session(self, sid, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            session = request.env['encoach.session'].sudo().browse(sid)
+            if not session.exists():
+                return self._error_response('Session not found', 404)
+
+            session.unlink()
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Delete session error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/stats.py

@@ -0,0 +1,137 @@
+import json
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class StatsController(EncoachMixin, http.Controller):
+
+    # -------------------------------------------------------------- save
+    @http.route('/api/stats', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def save_stats(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            stat_id = body.get('_id') or body.get('id')
+            Stat = request.env['encoach.stat'].sudo()
+
+            vals = {}
+            if body.get('sessionId'):
+                vals['session_id'] = int(body['sessionId'])
+            if body.get('module'):
+                vals['module'] = body['module']
+            if 'score' in body:
+                vals['score'] = body['score']
+            if body.get('result') is not None:
+                vals['result'] = json.dumps(body['result']) if isinstance(body['result'], dict) else body['result']
+            if body.get('examId'):
+                vals['exam_id'] = int(body['examId'])
+            if body.get('assignmentId'):
+                vals['assignment_id'] = int(body['assignmentId'])
+
+            if stat_id:
+                record = Stat.browse(int(stat_id))
+                if record.exists():
+                    record.write(vals)
+                    return self._json_response(self._serialize_stat(record))
+
+            vals['user_id'] = user.id
+            record = Stat.create(vals)
+            return self._json_response(self._serialize_stat(record), status=201)
+        except Exception:
+            _logger.exception("Save stats error")
+            return self._error_response('Internal server error', 500)
+
+    # --------------------------------------------------------------- get
+    @http.route(
+        '/api/stats/<int:stat_id>', type='http', auth='public',
+        methods=['GET', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def get_stat(self, stat_id, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            stat = request.env['encoach.stat'].sudo().browse(stat_id)
+            if not stat.exists():
+                return self._error_response('Stat not found', 404)
+
+            return self._json_response(self._serialize_stat(stat))
+        except Exception:
+            _logger.exception("Get stat error")
+            return self._error_response('Internal server error', 500)
+
+    # --------------------------------------------------------- statistical
+    @http.route('/api/statistical', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def statistical_query(self, **kwargs):
+        """Run statistical queries against exam stats."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            Stat = request.env['encoach.stat'].sudo()
+
+            domain = []
+            user_id = body.get('userId')
+            if user_id:
+                domain.append(('user_id', '=', int(user_id)))
+
+            module = body.get('module')
+            if module:
+                domain.append(('module', '=', module))
+
+            group_id = body.get('groupId')
+            if group_id:
+                domain.append(('assignment_id.group_id', '=', int(group_id)))
+
+            assignment_id = body.get('assignmentId')
+            if assignment_id:
+                domain.append(('assignment_id', '=', int(assignment_id)))
+
+            date_from = body.get('dateFrom')
+            if date_from:
+                domain.append(('create_date', '>=', date_from))
+
+            date_to = body.get('dateTo')
+            if date_to:
+                domain.append(('create_date', '<=', date_to))
+
+            stats = Stat.search(domain, order='create_date desc')
+
+            scores = [s.score for s in stats if s.score]
+            avg_score = sum(scores) / len(scores) if scores else 0
+            total = len(stats)
+
+            module_breakdown = {}
+            for s in stats:
+                mod = getattr(s, 'module', 'unknown')
+                if mod not in module_breakdown:
+                    module_breakdown[mod] = {'count': 0, 'scores': []}
+                module_breakdown[mod]['count'] += 1
+                if s.score:
+                    module_breakdown[mod]['scores'].append(s.score)
+
+            for mod, data in module_breakdown.items():
+                data['average'] = sum(data['scores']) / len(data['scores']) if data['scores'] else 0
+                del data['scores']
+
+            return self._json_response({
+                'total': total,
+                'averageScore': round(avg_score, 2),
+                'moduleBreakdown': module_breakdown,
+                'stats': [self._serialize_stat(s) for s in stats[:100]],
+            })
+        except Exception:
+            _logger.exception("Statistical query error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/storage.py

@@ -0,0 +1,82 @@
+import base64
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class StorageController(EncoachMixin, http.Controller):
+
+    # ------------------------------------------------------------- upload
+    @http.route('/api/storage', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def upload_file(self, **kwargs):
+        """Upload a file and return its public URL via ``ir.attachment``."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            uploaded = request.httprequest.files.get('file')
+            if not uploaded:
+                return self._error_response('No file provided', 400)
+
+            data = uploaded.read()
+            attachment = request.env['ir.attachment'].sudo().create({
+                'name': uploaded.filename,
+                'datas': base64.b64encode(data),
+                'res_model': 'encoach.storage',
+                'type': 'binary',
+                'public': True,
+            })
+
+            base_url = request.env['ir.config_parameter'].sudo().get_param('web.base.url', '')
+            file_url = f"{base_url}/web/content/{attachment.id}/{uploaded.filename}"
+
+            return self._json_response({
+                'ok': True,
+                'id': attachment.id,
+                'url': file_url,
+                'filename': uploaded.filename,
+                'size': len(data),
+            })
+        except Exception:
+            _logger.exception("Upload file error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------------------ delete
+    @http.route('/api/storage/delete', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def delete_file(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            attachment_id = body.get('id') or body.get('attachmentId')
+            url = body.get('url', '')
+
+            Attachment = request.env['ir.attachment'].sudo()
+
+            if attachment_id:
+                att = Attachment.browse(int(attachment_id))
+            elif url:
+                parts = url.rstrip('/').split('/')
+                try:
+                    att_id = int(parts[-2]) if len(parts) >= 2 else 0
+                except (ValueError, IndexError):
+                    att_id = 0
+                att = Attachment.browse(att_id) if att_id else Attachment
+            else:
+                return self._error_response('id or url is required', 400)
+
+            if att.exists():
+                att.unlink()
+
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Delete file error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/subscriptions.py

@@ -0,0 +1,192 @@
+import json
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class SubscriptionsController(EncoachMixin, http.Controller):
+
+    # ---------------------------------------------------------- packages
+    @http.route('/api/packages', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def list_packages(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            domain = [('is_active', '=', True)]
+            entity_id = kwargs.get('entityID')
+            if entity_id:
+                domain.append(('entity_id', '=', int(entity_id)))
+
+            packages = request.env['encoach.package'].sudo().search(domain, order='price asc')
+            return self._json_response([p.to_encoach_dict() for p in packages])
+        except Exception:
+            _logger.exception("List packages error")
+            return self._error_response('Internal server error', 500)
+
+    # ---------------------------------------------------- stripe checkout
+    @http.route('/api/stripe', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def create_stripe_checkout(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            package_id = body.get('packageId')
+            if not package_id:
+                return self._error_response('packageId is required', 400)
+
+            package = request.env['encoach.package'].sudo().browse(int(package_id))
+            if not package.exists():
+                return self._error_response('Package not found', 404)
+
+            success_url = body.get('successUrl', '')
+            cancel_url = body.get('cancelUrl', '')
+            discount_code = body.get('discountCode')
+
+            from odoo.addons.encoach_subscription.services.stripe_service import EncoachStripeService
+            service = EncoachStripeService(request.env)
+            result = service.create_checkout_session(
+                user=user,
+                package=package,
+                success_url=success_url,
+                cancel_url=cancel_url,
+                discount_code=discount_code,
+            )
+
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Stripe checkout error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------ paypal create order
+    @http.route('/api/paypal', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def create_paypal_order(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            package_id = body.get('packageId')
+            if not package_id:
+                return self._error_response('packageId is required', 400)
+
+            package = request.env['encoach.package'].sudo().browse(int(package_id))
+            if not package.exists():
+                return self._error_response('Package not found', 404)
+
+            discount_code = body.get('discountCode')
+
+            from odoo.addons.encoach_subscription.services.paypal_service import EncoachPaypalService
+            service = EncoachPaypalService(request.env)
+            result = service.create_order(
+                user=user,
+                package=package,
+                discount_code=discount_code,
+            )
+
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("PayPal create order error")
+            return self._error_response('Internal server error', 500)
+
+    # ---------------------------------------------- paypal capture order
+    @http.route('/api/paypal/approve', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def capture_paypal_order(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            order_id = body.get('orderId')
+            if not order_id:
+                return self._error_response('orderId is required', 400)
+
+            from odoo.addons.encoach_subscription.services.paypal_service import EncoachPaypalService
+            service = EncoachPaypalService(request.env)
+            result = service.capture_order(
+                user=user,
+                order_id=order_id,
+            )
+
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("PayPal capture error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------ paymob intention
+    @http.route('/api/paymob', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def create_paymob_intention(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            package_id = body.get('packageId')
+            if not package_id:
+                return self._error_response('packageId is required', 400)
+
+            package = request.env['encoach.package'].sudo().browse(int(package_id))
+            if not package.exists():
+                return self._error_response('Package not found', 404)
+
+            discount_code = body.get('discountCode')
+
+            from odoo.addons.encoach_subscription.services.paymob_service import EncoachPaymobService
+            service = EncoachPaymobService(request.env)
+            result = service.create_intention(
+                user=user,
+                package=package,
+                discount_code=discount_code,
+            )
+
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Paymob intention error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------ stripe webhook
+    @http.route('/api/stripe/webhook', type='http', auth='public', methods=['POST'], csrf=False, cors='*')
+    def stripe_webhook(self, **kwargs):
+        try:
+            payload = request.httprequest.get_data(as_text=True)
+            sig_header = request.httprequest.headers.get('Stripe-Signature', '')
+
+            from odoo.addons.encoach_subscription.services.stripe_service import EncoachStripeService
+            service = EncoachStripeService(request.env)
+            result = service.handle_webhook(payload, sig_header)
+
+            if 'error' in result:
+                return self._error_response(result['error'], 400)
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Stripe webhook error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------ paymob webhook
+    @http.route('/api/paymob/webhook', type='http', auth='public', methods=['POST'], csrf=False, cors='*')
+    def paymob_webhook(self, **kwargs):
+        try:
+            payload = request.httprequest.get_data(as_text=True)
+            hmac_header = request.httprequest.args.get('hmac', '')
+
+            from odoo.addons.encoach_subscription.services.paymob_service import EncoachPaymobService
+            service = EncoachPaymobService(request.env)
+            result = service.verify_transaction(json.loads(payload), hmac_header)
+
+            if not result or 'error' in result:
+                return self._error_response(result.get('error', 'Verification failed') if result else 'Verification failed', 400)
+            return self._json_response(result)
+        except Exception:
+            _logger.exception("Paymob webhook error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/tickets.py

@@ -0,0 +1,128 @@
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class TicketsController(EncoachMixin, http.Controller):
+
+    # --------------------------------------------------------------- list
+    @http.route('/api/tickets', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def list_tickets(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            domain = []
+            user_type = getattr(user, 'encoach_user_type', 'student')
+            if user_type not in ('admin', 'developer'):
+                domain.append(('user_id', '=', user.id))
+
+            status = kwargs.get('status')
+            if status:
+                domain.append(('status', '=', status))
+
+            offset, limit, page = self._paginate_params(kwargs)
+            Ticket = request.env['encoach.ticket'].sudo()
+            total = Ticket.search_count(domain)
+            records = Ticket.search(domain, offset=offset, limit=limit, order='create_date desc')
+
+            return self._json_response({
+                'tickets': [self._serialize_ticket(t) for t in records],
+                'total': total,
+                'page': page,
+                'limit': limit,
+            })
+        except Exception:
+            _logger.exception("List tickets error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------------------------- create
+    @http.route('/api/tickets', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def create_ticket(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            subject = body.get('subject', '').strip()
+            if not subject:
+                return self._error_response('Subject is required', 400)
+
+            vals = {
+                'subject': subject,
+                'description': body.get('description', ''),
+                'user_id': user.id,
+                'status': 'open',
+            }
+            if body.get('priority'):
+                vals['priority'] = body['priority']
+            if body.get('category'):
+                vals['category'] = body['category']
+
+            ticket = request.env['encoach.ticket'].sudo().create(vals)
+            return self._json_response(self._serialize_ticket(ticket), status=201)
+        except Exception:
+            _logger.exception("Create ticket error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------------------------- update
+    @http.route(
+        '/api/tickets/<int:tid>', type='http', auth='public',
+        methods=['PATCH', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def update_ticket(self, tid, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            ticket = request.env['encoach.ticket'].sudo().browse(tid)
+            if not ticket.exists():
+                return self._error_response('Ticket not found', 404)
+
+            body = self._get_json_body()
+            vals = {}
+            if 'subject' in body:
+                vals['subject'] = body['subject']
+            if 'description' in body:
+                vals['description'] = body['description']
+            if 'status' in body:
+                vals['status'] = body['status']
+            if 'priority' in body:
+                vals['priority'] = body['priority']
+
+            if vals:
+                ticket.write(vals)
+
+            return self._json_response(self._serialize_ticket(ticket))
+        except Exception:
+            _logger.exception("Update ticket error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------------------------- delete
+    @http.route(
+        '/api/tickets/<int:tid>', type='http', auth='public',
+        methods=['DELETE', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def delete_ticket(self, tid, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            ticket = request.env['encoach.ticket'].sudo().browse(tid)
+            if not ticket.exists():
+                return self._error_response('Ticket not found', 404)
+
+            ticket.unlink()
+            return self._json_response({'ok': True})
+        except Exception:
+            _logger.exception("Delete ticket error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/training.py

@@ -0,0 +1,117 @@
+import json
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class TrainingController(EncoachMixin, http.Controller):
+
+    # ----------------------------------------------------------- generate
+    @http.route('/api/training', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def generate_training(self, **kwargs):
+        """Generate personalised training content using FAISS + GPT."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            target_user_id = body.get('userID', user.id)
+            stats = body.get('stats', [])
+
+            Training = request.env['encoach.training'].sudo()
+            training = Training.generate_training(
+                user_id=int(target_user_id),
+                stats=stats,
+            )
+
+            return self._json_response({
+                'id': training.id,
+                '_id': str(training.id),
+            })
+        except Exception:
+            _logger.exception("Generate training error")
+            return self._error_response('Internal server error', 500)
+
+    # -------------------------------------------------------- get record
+    @http.route(
+        '/api/training/<int:tid>', type='http', auth='public',
+        methods=['GET', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def get_training(self, tid, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            training = request.env['encoach.training'].sudo().browse(tid)
+            if not training.exists():
+                return self._error_response('Training record not found', 404)
+
+            return self._json_response({
+                '_id': str(training.id),
+                'id': training.id,
+                'userId': str(training.user_id.id) if training.user_id else None,
+                'createdAt': training.created_at.isoformat() if getattr(training, 'created_at', None) else (
+                    training.create_date.isoformat() if training.create_date else None
+                ),
+                'exams': json.loads(training.exams) if getattr(training, 'exams', None) else [],
+                'tips': json.loads(training.tips) if getattr(training, 'tips', None) else {},
+                'weakAreas': json.loads(training.weak_areas) if getattr(training, 'weak_areas', None) else [],
+            })
+        except Exception:
+            _logger.exception("Get training error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------------------- tips
+    @http.route('/api/training/tips', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def fetch_tips(self, **kwargs):
+        """Retrieve contextual tips using FAISS semantic search + GPT."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            Training = request.env['encoach.training'].sudo()
+            tips = Training.fetch_tips(
+                context=body.get('context', ''),
+                question=body.get('question', ''),
+                answer=body.get('answer', ''),
+                correct_answer=body.get('correct_answer', ''),
+            )
+
+            return self._json_response({'tips': tips})
+        except Exception:
+            _logger.exception("Fetch tips error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------------ walkthrough
+    @http.route('/api/training/walkthrough', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def get_walkthrough(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            Walkthrough = request.env['encoach.walkthrough'].sudo()
+            records = Walkthrough.search([], order='sequence asc')
+
+            data = [{
+                '_id': str(w.id),
+                'id': w.id,
+                'title': getattr(w, 'title', ''),
+                'description': getattr(w, 'description', ''),
+                'steps': json.loads(w.steps) if getattr(w, 'steps', None) else [],
+                'module': getattr(w, 'module', ''),
+            } for w in records]
+
+            return self._json_response(data)
+        except Exception:
+            _logger.exception("Get walkthrough error")
+            return self._error_response('Internal server error', 500)

encoach_api/controllers/users.py

@@ -0,0 +1,185 @@
+import logging
+
+from odoo import http
+from odoo.http import request
+
+from .base import EncoachMixin
+
+_logger = logging.getLogger(__name__)
+
+
+class UsersController(EncoachMixin, http.Controller):
+
+    # ---------------------------------------------------------- current user
+    @http.route('/api/user', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def get_current_user(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+            return self._json_response(self._serialize(user))
+        except Exception:
+            _logger.exception("Get current user error")
+            return self._error_response('Internal server error', 500)
+
+    # ----------------------------------------------------------- update user
+    @http.route(
+        '/api/users/update', type='http', auth='public',
+        methods=['POST', 'PATCH', 'OPTIONS'], csrf=False, cors='*',
+    )
+    def update_user(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            vals = {}
+            field_map = {
+                'name': 'name',
+                'phone': 'phone',
+                'nativeLanguage': 'encoach_native_language',
+                'country': 'encoach_country',
+                'learningGoal': 'encoach_learning_goal',
+                'image': 'encoach_image_url',
+            }
+            for api_field, odoo_field in field_map.items():
+                if api_field in body:
+                    vals[odoo_field] = body[api_field]
+
+            if 'password' in body and body['password']:
+                vals['password'] = body['password']
+
+            if vals:
+                user.sudo().write(vals)
+
+            updated = request.env['res.users'].sudo().browse(user.id)
+            return self._json_response(self._serialize(updated))
+        except Exception:
+            _logger.exception("Update user error")
+            return self._error_response('Internal server error', 500)
+
+    # ------------------------------------------------------------- list users
+    @http.route('/api/users/list', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def list_users(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            offset, limit, page = self._paginate_params(kwargs)
+            domain = []
+
+            search = kwargs.get('search', '').strip()
+            if search:
+                domain.append('|')
+                domain.append(('name', 'ilike', search))
+                domain.append(('login', 'ilike', search))
+
+            user_type = kwargs.get('type')
+            if user_type:
+                domain.append(('encoach_user_type', '=', user_type))
+
+            entity_id = kwargs.get('entityID')
+            if entity_id:
+                domain.append(('encoach_entity_id', '=', int(entity_id)))
+
+            Users = request.env['res.users'].sudo()
+            total = Users.search_count(domain)
+            records = Users.search(domain, offset=offset, limit=limit, order='name asc')
+
+            return self._json_response({
+                'users': [self._serialize(u) for u in records],
+                'total': total,
+                'page': page,
+                'limit': limit,
+            })
+        except Exception:
+            _logger.exception("List users error")
+            return self._error_response('Internal server error', 500)
+
+    # ---------------------------------------------------------- get user by id
+    @http.route('/api/users/<int:user_id>', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def get_user(self, user_id, **kwargs):
+        try:
+            auth_user = self._authenticate()
+            if not auth_user:
+                return self._error_response('Unauthorized', 401)
+
+            target = request.env['res.users'].sudo().browse(user_id)
+            if not target.exists():
+                return self._error_response('User not found', 404)
+
+            return self._json_response(self._serialize(target))
+        except Exception:
+            _logger.exception("Get user error")
+            return self._error_response('Internal server error', 500)
+
+    # --------------------------------------------------- user controller action
+    @http.route('/api/users/controller', type='http', auth='public', methods=['POST', 'OPTIONS'], csrf=False, cors='*')
+    def user_controller(self, **kwargs):
+        """Handle user controller actions such as transferring users between groups."""
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            body = self._get_json_body()
+            action = body.get('action')
+            if not action:
+                return self._error_response('Action is required', 400)
+
+            Group = request.env['encoach.group'].sudo()
+
+            if action == 'transfer':
+                user_ids = body.get('userIds', [])
+                from_group_id = body.get('fromGroupId')
+                to_group_id = body.get('toGroupId')
+                if not user_ids or not to_group_id:
+                    return self._error_response('userIds and toGroupId are required', 400)
+
+                if from_group_id:
+                    from_group = Group.browse(int(from_group_id))
+                    if from_group.exists():
+                        from_group.write({
+                            'participant_ids': [(3, int(uid)) for uid in user_ids],
+                        })
+
+                to_group = Group.browse(int(to_group_id))
+                if not to_group.exists():
+                    return self._error_response('Target group not found', 404)
+                to_group.write({
+                    'participant_ids': [(4, int(uid)) for uid in user_ids],
+                })
+                return self._json_response({'ok': True})
+
+            if action == 'remove':
+                user_ids = body.get('userIds', [])
+                group_id = body.get('groupId')
+                if not user_ids or not group_id:
+                    return self._error_response('userIds and groupId are required', 400)
+                group = Group.browse(int(group_id))
+                if group.exists():
+                    group.write({
+                        'participant_ids': [(3, int(uid)) for uid in user_ids],
+                    })
+                return self._json_response({'ok': True})
+
+            return self._error_response(f'Unknown action: {action}', 400)
+        except Exception:
+            _logger.exception("User controller error")
+            return self._error_response('Internal server error', 500)
+
+    # ---------------------------------------------------------- user balance
+    @http.route('/api/users/balance', type='http', auth='public', methods=['GET', 'OPTIONS'], csrf=False, cors='*')
+    def user_balance(self, **kwargs):
+        try:
+            user = self._authenticate()
+            if not user:
+                return self._error_response('Unauthorized', 401)
+
+            balance = getattr(user, 'encoach_balance', 0)
+            return self._json_response({'balance': balance})
+        except Exception:
+            _logger.exception("User balance error")
+            return self._error_response('Internal server error', 500)

encoach_api/security/ir.model.access.csv

@@ -0,0 +1 @@
+id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink

encoach_api/tests/__init__.py

@@ -0,0 +1 @@
+from . import test_endpoints

encoach_api/tests/test_endpoints.py

@@ -0,0 +1,483 @@
+"""
+Integration tests verifying all 73 frontend endpoint mappings from
+ODOO_MIGRATION_FRONTEND_SRS.md Section 4 against the Odoo REST API.
+
+Run with:
+    ./odoo-bin -c odoo.conf --test-enable -d test_db --stop-after-init -i encoach_api
+"""
+import json
+import logging
+
+from odoo.tests.common import HttpCase, tagged
+
+_logger = logging.getLogger(__name__)
+
+
+@tagged("post_install", "-at_install", "encoach")
+class TestEncoachEndpoints(HttpCase):
+
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+        cls.env["ir.config_parameter"].sudo().set_param(
+            "encoach.jwt_secret", "test_secret_key_for_ci"
+        )
+        cls.admin_user = cls.env["res.users"].sudo().create({
+            "login": "encoach_test_admin@example.com",
+            "name": "Test Admin",
+            "password": "admin_pass_123",
+            "encoach_type": "admin",
+        })
+        cls.student_user = cls.env["res.users"].sudo().create({
+            "login": "encoach_test_student@example.com",
+            "name": "Test Student",
+            "password": "student_pass_123",
+            "encoach_type": "student",
+        })
+        cls.entity = cls.env["encoach.entity"].sudo().create({
+            "name": "Test Entity",
+            "label": "Test Org",
+            "licenses": 100,
+        })
+        cls.exam = cls.env["encoach.exam"].sudo().create({
+            "module": "reading",
+            "label": "Test Reading Exam",
+            "access": "public",
+            "parts": [{"text": "Sample passage", "exercises": []}],
+        })
+        cls.group = cls.env["encoach.group"].sudo().create({
+            "name": "Test Group",
+            "admin_id": cls.admin_user.id,
+        })
+        cls.package = cls.env["encoach.package"].sudo().create({
+            "name": "Basic Plan",
+            "price": 9.99,
+            "currency": "USD",
+            "duration_days": 30,
+        })
+
+    def _login_and_get_token(self, email="encoach_test_admin@example.com", password="admin_pass_123"):
+        resp = self.url_open(
+            "/api/login",
+            data=json.dumps({"email": email, "password": password}),
+            headers={"Content-Type": "application/json"},
+        )
+        self.assertEqual(resp.status_code, 200)
+        data = resp.json()
+        self.assertIn("token", data)
+        return data["token"]
+
+    def _auth_headers(self, token):
+        return {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        }
+
+    # ================================================================
+    #  Section 4.1: Auth endpoints
+    # ================================================================
+
+    def test_0101_login(self):
+        """POST /api/login -- valid credentials"""
+        resp = self.url_open(
+            "/api/login",
+            data=json.dumps({"email": "encoach_test_admin@example.com", "password": "admin_pass_123"}),
+            headers={"Content-Type": "application/json"},
+        )
+        self.assertEqual(resp.status_code, 200)
+        body = resp.json()
+        self.assertIn("token", body)
+        self.assertIn("user", body)
+
+    def test_0102_login_bad_password(self):
+        """POST /api/login -- wrong password returns 401"""
+        resp = self.url_open(
+            "/api/login",
+            data=json.dumps({"email": "encoach_test_admin@example.com", "password": "wrong"}),
+            headers={"Content-Type": "application/json"},
+        )
+        self.assertIn(resp.status_code, [401, 400])
+
+    def test_0103_logout(self):
+        """POST /api/logout -- always succeeds"""
+        resp = self.url_open(
+            "/api/logout",
+            data=json.dumps({}),
+            headers={"Content-Type": "application/json"},
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    def test_0104_reset(self):
+        """POST /api/reset -- sends reset email"""
+        resp = self.url_open(
+            "/api/reset",
+            data=json.dumps({"email": "encoach_test_admin@example.com"}),
+            headers={"Content-Type": "application/json"},
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    def test_0105_send_verification(self):
+        """POST /api/reset/sendVerification"""
+        resp = self.url_open(
+            "/api/reset/sendVerification",
+            data=json.dumps({"email": "encoach_test_admin@example.com"}),
+            headers={"Content-Type": "application/json"},
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    # ================================================================
+    #  Section 4.2: User endpoints
+    # ================================================================
+
+    def test_0201_get_current_user(self):
+        """GET /api/user -- returns current JWT user"""
+        token = self._login_and_get_token()
+        resp = self.url_open("/api/user", headers=self._auth_headers(token))
+        self.assertEqual(resp.status_code, 200)
+        body = resp.json()
+        self.assertIn("email", body.get("user", body))
+
+    def test_0202_update_user(self):
+        """POST /api/users/update -- update profile"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/users/update",
+            data=json.dumps({"name": "Updated Admin"}),
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    def test_0203_list_users(self):
+        """GET /api/users/list -- paginated list"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/users/list?page=1&limit=10",
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    def test_0204_get_user_by_id(self):
+        """GET /api/users/<id>"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            f"/api/users/{self.student_user.id}",
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    def test_0205_user_balance(self):
+        """GET /api/users/balance"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/users/balance",
+            headers=self._auth_headers(token),
+        )
+        self.assertIn(resp.status_code, [200, 404])
+
+    # ================================================================
+    #  Section 4.3: Group endpoints
+    # ================================================================
+
+    def test_0301_list_groups(self):
+        """GET /api/groups"""
+        token = self._login_and_get_token()
+        resp = self.url_open("/api/groups", headers=self._auth_headers(token))
+        self.assertEqual(resp.status_code, 200)
+
+    def test_0302_create_group(self):
+        """POST /api/groups"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/groups",
+            data=json.dumps({"name": "New Test Group"}),
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    def test_0303_update_group(self):
+        """PATCH /api/groups/<id>"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            f"/api/groups/{self.group.id}",
+            data=json.dumps({"name": "Renamed Group"}),
+            headers=self._auth_headers(token),
+        )
+        self.assertIn(resp.status_code, [200, 405])
+
+    def test_0304_delete_group(self):
+        """DELETE /api/groups/<id>"""
+        token = self._login_and_get_token()
+        new_group = self.env["encoach.group"].sudo().create({
+            "name": "To Delete",
+            "admin_id": self.admin_user.id,
+        })
+        resp = self.url_open(
+            f"/api/groups/{new_group.id}",
+            headers=self._auth_headers(token),
+        )
+        self.assertIn(resp.status_code, [200, 204, 405])
+
+    # ================================================================
+    #  Section 4.4: Exam endpoints
+    # ================================================================
+
+    def test_0401_list_exams(self):
+        """GET /api/exam"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/exam?module=reading",
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    def test_0402_create_exam(self):
+        """POST /api/exam/reading"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/exam/reading",
+            data=json.dumps({
+                "label": "Generated Reading",
+                "parts": [{"text": "Test", "exercises": []}],
+            }),
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    def test_0403_get_exam(self):
+        """GET /api/exam/reading/<id>"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            f"/api/exam/reading/{self.exam.id}",
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    def test_0404_update_exam(self):
+        """PATCH /api/exam/reading/<id>"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            f"/api/exam/reading/{self.exam.id}",
+            data=json.dumps({"label": "Updated Label"}),
+            headers=self._auth_headers(token),
+        )
+        self.assertIn(resp.status_code, [200, 405])
+
+    def test_0405_delete_exam(self):
+        """DELETE /api/exam/reading/<id>"""
+        token = self._login_and_get_token()
+        disposable = self.env["encoach.exam"].sudo().create({
+            "module": "reading",
+            "label": "To Delete",
+            "access": "public",
+            "parts": [],
+        })
+        resp = self.url_open(
+            f"/api/exam/reading/{disposable.id}",
+            headers=self._auth_headers(token),
+        )
+        self.assertIn(resp.status_code, [200, 204, 405])
+
+    # ================================================================
+    #  Section 4.5: Assignment endpoints
+    # ================================================================
+
+    def test_0501_create_assignment(self):
+        """POST /api/assignments"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/assignments",
+            data=json.dumps({
+                "name": "Test Assignment",
+                "exams": [self.exam.id],
+                "assignees": [self.student_user.id],
+            }),
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    def test_0502_list_assignments(self):
+        """GET /api/assignments"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/assignments",
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    # ================================================================
+    #  Section 4.6: Session endpoints
+    # ================================================================
+
+    def test_0601_create_session(self):
+        """POST /api/sessions"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/sessions",
+            data=json.dumps({"examData": {"module": "reading"}}),
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    # ================================================================
+    #  Section 4.7: Stats endpoints
+    # ================================================================
+
+    def test_0701_create_stat(self):
+        """POST /api/stats"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/stats",
+            data=json.dumps({
+                "module": "reading",
+                "exercise": "fillBlanks",
+                "solutions": [],
+                "scoreCorrect": 5,
+                "scoreTotal": 10,
+            }),
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    def test_0702_statistical(self):
+        """POST /api/statistical"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/statistical",
+            data=json.dumps({"userId": self.admin_user.id}),
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    # ================================================================
+    #  Section 4.8: Training endpoints
+    # ================================================================
+
+    def test_0801_get_walkthrough(self):
+        """GET /api/training/walkthrough"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/training/walkthrough",
+            headers=self._auth_headers(token),
+        )
+        self.assertIn(resp.status_code, [200, 404])
+
+    # ================================================================
+    #  Section 4.9: Package/Subscription endpoints
+    # ================================================================
+
+    def test_0901_list_packages(self):
+        """GET /api/packages"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/packages",
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    # ================================================================
+    #  Section 4.10: Registration endpoints
+    # ================================================================
+
+    def test_1001_register(self):
+        """POST /api/register"""
+        resp = self.url_open(
+            "/api/register",
+            data=json.dumps({
+                "email": "newuser_test@example.com",
+                "password": "test_pass_123",
+                "name": "New Test User",
+            }),
+            headers={"Content-Type": "application/json"},
+        )
+        self.assertIn(resp.status_code, [200, 201])
+
+    def test_1002_validate_code(self):
+        """GET /api/code/<code>"""
+        code = self.env["encoach.code"].sudo().create({
+            "code": "TESTCODE",
+            "creator_id": self.admin_user.id,
+            "max_uses": 10,
+        })
+        resp = self.url_open("/api/code/TESTCODE")
+        self.assertEqual(resp.status_code, 200)
+
+    # ================================================================
+    #  Section 4.11: Ticket endpoints
+    # ================================================================
+
+    def test_1101_create_ticket(self):
+        """POST /api/tickets"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/tickets",
+            data=json.dumps({
+                "subject": "Help needed",
+                "description": "I have a problem",
+                "type": "help",
+            }),
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    def test_1102_list_tickets(self):
+        """GET /api/tickets"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/tickets",
+            headers=self._auth_headers(token),
+        )
+        self.assertEqual(resp.status_code, 200)
+
+    # ================================================================
+    #  Section 4.12: Evaluation endpoints (stub -- AI services not configured)
+    # ================================================================
+
+    def test_1201_evaluate_status(self):
+        """GET /api/evaluate/status -- should return 200 even with no data"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/evaluate/status?sessionId=0&exerciseId=none",
+            headers=self._auth_headers(token),
+        )
+        self.assertIn(resp.status_code, [200, 404])
+
+    # ================================================================
+    #  Section 4.13: Storage endpoints
+    # ================================================================
+
+    def test_1301_storage_delete(self):
+        """POST /api/storage/delete -- no-op when file missing"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/storage/delete",
+            data=json.dumps({"url": "nonexistent.png"}),
+            headers=self._auth_headers(token),
+        )
+        self.assertIn(resp.status_code, [200, 404])
+
+    # ================================================================
+    #  Section 4.14: Grading endpoints (stub -- AI not configured)
+    # ================================================================
+
+    def test_1401_grading_summary(self):
+        """POST /api/exam/grade/summary"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/exam/grade/summary",
+            data=json.dumps({"sections": []}),
+            headers=self._auth_headers(token),
+        )
+        self.assertIn(resp.status_code, [200, 400, 500])
+
+    # ================================================================
+    #  Section 4.15: Avatar endpoint
+    # ================================================================
+
+    def test_1501_list_avatars(self):
+        """GET /api/exam/speaking/avatars"""
+        token = self._login_and_get_token()
+        resp = self.url_open(
+            "/api/exam/speaking/avatars",
+            headers=self._auth_headers(token),
+        )
+        self.assertIn(resp.status_code, [200, 404])

encoach_assignment/__init__.py

@@ -0,0 +1 @@
+from . import models

encoach_assignment/__manifest__.py

@@ -0,0 +1,14 @@
+{
+    "name": "EnCoach Assignment",
+    "version": "19.0.1.0.0",
+    "category": "Education",
+    "summary": "Exam assignments for teachers and students",
+    "depends": ["encoach_core", "encoach_exam"],
+    "data": [
+        "security/ir.model.access.csv",
+        "security/rules.xml",
+        "views/assignment_views.xml",
+    ],
+    "installable": True,
+    "license": "LGPL-3",
+}

encoach_assignment/models/__init__.py

@@ -0,0 +1 @@
+from . import assignment

encoach_assignment/models/assignment.py

@@ -0,0 +1,87 @@
+from odoo import models, fields
+
+INSTRUCTOR_GENDER = [
+    ("male", "Male"),
+    ("female", "Female"),
+]
+
+
+class EncoachAssignment(models.Model):
+    _name = "encoach.assignment"
+    _description = "EnCoach Assignment"
+
+    name = fields.Char(required=True)
+    assigner_id = fields.Many2one(
+        "res.users", string="Assigner", default=lambda self: self.env.uid,
+    )
+    assignee_ids = fields.Many2many(
+        "res.users", "encoach_assignment_assignee_rel",
+        "assignment_id", "user_id", string="Assignees",
+    )
+    exam_ids = fields.Many2many(
+        "encoach.exam", "encoach_assignment_exam_rel",
+        "assignment_id", "exam_id", string="Exams",
+    )
+    results = fields.Json(
+        help="Array of {user, type, stats} result objects per assignee",
+    )
+    instructor_gender = fields.Selection(INSTRUCTOR_GENDER)
+    start_date = fields.Datetime()
+    end_date = fields.Datetime()
+    teacher_ids = fields.Many2many(
+        "res.users", "encoach_assignment_teacher_rel",
+        "assignment_id", "user_id", string="Teachers",
+    )
+    archived = fields.Boolean(default=False)
+    released = fields.Boolean(default=False)
+    started = fields.Boolean(default=False)
+    auto_start = fields.Boolean(default=False)
+    entity_id = fields.Many2one("encoach.entity", index=True)
+    legacy_id = fields.Char(index=True)
+
+    def action_start(self):
+        for rec in self:
+            rec.started = True
+
+    def action_release(self):
+        for rec in self:
+            rec.released = True
+
+    def action_archive(self):
+        for rec in self:
+            rec.archived = True
+
+    def action_unarchive(self):
+        for rec in self:
+            rec.archived = False
+
+    def to_encoach_dict(self):
+        self.ensure_one()
+        exams = []
+        for exam in self.exam_ids:
+            exams.append({
+                "id": exam.id,
+                "module": exam.module,
+                "assignee": None,
+            })
+        return {
+            "id": self.id,
+            "name": self.name,
+            "assigner": self.assigner_id.id if self.assigner_id else None,
+            "assignees": self.assignee_ids.ids,
+            "results": self.results or [],
+            "exams": exams,
+            "instructorGender": self.instructor_gender,
+            "startDate": (
+                self.start_date.isoformat() if self.start_date else None
+            ),
+            "endDate": (
+                self.end_date.isoformat() if self.end_date else None
+            ),
+            "teachers": self.teacher_ids.ids,
+            "archived": self.archived,
+            "released": self.released,
+            "start": self.started,
+            "autoStart": self.auto_start,
+            "entity": self.entity_id.id if self.entity_id else None,
+        }

encoach_assignment/security/ir.model.access.csv

@@ -0,0 +1,5 @@
+id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
+access_encoach_assignment_student,encoach.assignment.student,model_encoach_assignment,encoach_core.group_encoach_student,1,0,0,0
+access_encoach_assignment_teacher,encoach.assignment.teacher,model_encoach_assignment,encoach_core.group_encoach_teacher,1,1,1,0
+access_encoach_assignment_admin,encoach.assignment.admin,model_encoach_assignment,encoach_core.group_encoach_admin,1,1,1,1
+access_encoach_assignment_sysadmin,encoach.assignment.sysadmin,model_encoach_assignment,base.group_system,1,1,1,1

encoach_assignment/security/rules.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <data noupdate="1">
+        <record id="rule_assignment_student" model="ir.rule">
+            <field name="name">Students see assigned assignments</field>
+            <field name="model_id" ref="model_encoach_assignment"/>
+            <field name="groups" eval="[(4, ref('encoach_core.group_encoach_student'))]"/>
+            <field name="domain_force">[('assignee_ids', 'in', user.id)]</field>
+        </record>
+        <record id="rule_assignment_teacher" model="ir.rule">
+            <field name="name">Teachers see all assignments</field>
+            <field name="model_id" ref="model_encoach_assignment"/>
+            <field name="groups" eval="[(4, ref('encoach_core.group_encoach_teacher'))]"/>
+            <field name="domain_force">[(1, '=', 1)]</field>
+        </record>
+    </data>
+</odoo>

encoach_assignment/views/assignment_views.xml

@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <record id="view_encoach_assignment_tree" model="ir.ui.view">
+        <field name="name">encoach.assignment.tree</field>
+        <field name="model">encoach.assignment</field>
+        <field name="arch" type="xml">
+            <list string="Assignments">
+                <field name="name"/>
+                <field name="assigner_id"/>
+                <field name="start_date"/>
+                <field name="end_date"/>
+                <field name="instructor_gender"/>
+                <field name="started"/>
+                <field name="released"/>
+                <field name="archived"/>
+                <field name="entity_id"/>
+            </list>
+        </field>
+    </record>
+
+    <record id="view_encoach_assignment_form" model="ir.ui.view">
+        <field name="name">encoach.assignment.form</field>
+        <field name="model">encoach.assignment</field>
+        <field name="arch" type="xml">
+            <form string="Assignment">
+                <header>
+                    <button name="action_start" string="Start" type="object"
+                        class="btn-primary" invisible="started"/>
+                    <button name="action_release" string="Release" type="object"
+                        class="btn-primary" invisible="released or not started"/>
+                    <button name="action_archive" string="Archive" type="object"
+                        invisible="archived"/>
+                    <button name="action_unarchive" string="Unarchive" type="object"
+                        invisible="not archived"/>
+                    <field name="started" readonly="1"/>
+                    <field name="released" readonly="1"/>
+                    <field name="archived" readonly="1"/>
+                </header>
+                <sheet>
+                    <group>
+                        <group>
+                            <field name="name"/>
+                            <field name="assigner_id"/>
+                            <field name="instructor_gender"/>
+                            <field name="entity_id"/>
+                        </group>
+                        <group>
+                            <field name="start_date"/>
+                            <field name="end_date"/>
+                            <field name="auto_start"/>
+                        </group>
+                    </group>
+                    <notebook>
+                        <page string="Assignees" name="assignees">
+                            <field name="assignee_ids" widget="many2many_tags"/>
+                        </page>
+                        <page string="Exams" name="exams">
+                            <field name="exam_ids" widget="many2many_tags"/>
+                        </page>
+                        <page string="Teachers" name="teachers">
+                            <field name="teacher_ids" widget="many2many_tags"/>
+                        </page>
+                        <page string="Results" name="results">
+                            <field name="results" widget="json" nolabel="1" placeholder="[]"/>
+                        </page>
+                    </notebook>
+                </sheet>
+            </form>
+        </field>
+    </record>
+
+    <record id="action_encoach_assignment" model="ir.actions.act_window">
+        <field name="name">Assignments</field>
+        <field name="res_model">encoach.assignment</field>
+        <field name="view_mode">list,form</field>
+        <field name="help" type="html">
+            <p class="o_view_nocontent_smiling_face">
+                Create your first assignment.
+            </p>
+            <p>
+                Assignments link exams to assignees and teachers with start and end dates.
+            </p>
+        </field>
+    </record>
+
+    <menuitem id="menu_encoach_assignment"
+        name="Assignments"
+        parent="encoach_core.menu_encoach_classroom"
+        action="action_encoach_assignment"
+        sequence="20"/>
+</odoo>

encoach_classroom/__init__.py

@@ -0,0 +1 @@
+from . import models

encoach_classroom/__manifest__.py

@@ -0,0 +1,13 @@
+{
+    "name": "EnCoach Classroom",
+    "version": "19.0.1.0.0",
+    "category": "Education",
+    "summary": "Classroom groups for the EnCoach platform",
+    "depends": ["encoach_core"],
+    "data": [
+        "security/ir.model.access.csv",
+        "views/group_views.xml",
+    ],
+    "installable": True,
+    "license": "LGPL-3",
+}

encoach_classroom/models/__init__.py

@@ -0,0 +1 @@
+from . import group

encoach_classroom/models/group.py

@@ -0,0 +1,36 @@
+from odoo import models, fields
+
+
+class EncoachGroup(models.Model):
+    _name = "encoach.group"
+    _description = "EnCoach Classroom Group"
+
+    name = fields.Char(required=True)
+    admin_id = fields.Many2one("res.users", string="Admin", required=True)
+    participant_ids = fields.Many2many(
+        "res.users", "encoach_group_participant_rel", "group_id", "user_id",
+        string="Participants",
+    )
+    disable_editing = fields.Boolean(default=False)
+    entity_id = fields.Many2one("encoach.entity", index=True)
+    legacy_id = fields.Char(index=True)
+    participant_count = fields.Integer(
+        string="Participants",
+        compute="_compute_participant_count",
+        store=False,
+    )
+
+    def _compute_participant_count(self):
+        for rec in self:
+            rec.participant_count = len(rec.participant_ids)
+
+    def to_encoach_dict(self):
+        self.ensure_one()
+        return {
+            "id": self.id,
+            "name": self.name,
+            "admin": self.admin_id.id,
+            "participants": self.participant_ids.ids,
+            "disableEditing": self.disable_editing,
+            "entity": self.entity_id.id if self.entity_id else None,
+        }

encoach_classroom/security/ir.model.access.csv

@@ -0,0 +1,5 @@
+id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
+access_encoach_group_student,encoach.group.student,model_encoach_group,encoach_core.group_encoach_student,1,0,0,0
+access_encoach_group_teacher,encoach.group.teacher,model_encoach_group,encoach_core.group_encoach_teacher,1,1,1,0
+access_encoach_group_admin,encoach.group.admin,model_encoach_group,encoach_core.group_encoach_admin,1,1,1,1
+access_encoach_group_sysadmin,encoach.group.sysadmin,model_encoach_group,base.group_system,1,1,1,1

encoach_classroom/views/group_views.xml

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <record id="view_encoach_group_tree" model="ir.ui.view">
+        <field name="name">encoach.group.tree</field>
+        <field name="model">encoach.group</field>
+        <field name="arch" type="xml">
+            <list string="Groups">
+                <field name="name"/>
+                <field name="admin_id"/>
+                <field name="entity_id"/>
+                <field name="disable_editing"/>
+                <field name="participant_count" widget="badge"/>
+            </list>
+        </field>
+    </record>
+
+    <record id="view_encoach_group_form" model="ir.ui.view">
+        <field name="name">encoach.group.form</field>
+        <field name="model">encoach.group</field>
+        <field name="arch" type="xml">
+            <form string="Group">
+                <sheet>
+                    <group>
+                        <group>
+                            <field name="name"/>
+                            <field name="admin_id"/>
+                            <field name="entity_id"/>
+                            <field name="disable_editing"/>
+                        </group>
+                    </group>
+                    <notebook>
+                        <page string="Participants" name="participants">
+                            <field name="participant_ids">
+                                <list editable="bottom">
+                                    <field name="name"/>
+                                    <field name="login"/>
+                                    <field name="email"/>
+                                </list>
+                            </field>
+                        </page>
+                    </notebook>
+                </sheet>
+            </form>
+        </field>
+    </record>
+
+    <record id="action_encoach_group" model="ir.actions.act_window">
+        <field name="name">Groups</field>
+        <field name="res_model">encoach.group</field>
+        <field name="view_mode">list,form</field>
+        <field name="help" type="html">
+            <p class="o_view_nocontent_smiling_face">
+                Create your first group.
+            </p>
+            <p>
+                Groups organize participants in the classroom for assignments and exams.
+            </p>
+        </field>
+    </record>
+
+    <menuitem id="menu_encoach_group"
+        name="Groups"
+        parent="encoach_core.menu_encoach_classroom"
+        action="action_encoach_group"
+        sequence="10"/>
+</odoo>

encoach_core/__init__.py

@@ -0,0 +1 @@
+from . import models

encoach_core/__manifest__.py

@@ -0,0 +1,25 @@
+{
+    "name": "EnCoach Core",
+    "version": "19.0.1.0.0",
+    "category": "Education",
+    "summary": "Core models for the EnCoach IELTS platform",
+    "description": "User type extensions, entity management, roles, permissions, codes, invites.",
+    "depends": ["base", "mail"],
+    "data": [
+        "security/security.xml",
+        "security/ir.model.access.csv",
+        "data/constants.xml",
+        "views/menu.xml",
+        "views/entity_views.xml",
+        "views/role_views.xml",
+        "views/permission_views.xml",
+        "views/code_views.xml",
+        "views/invite_views.xml",
+        "views/user_entity_rel_views.xml",
+        "views/res_users_views.xml",
+        "data/assign_admin_group.xml",
+    ],
+    "installable": True,
+    "application": True,
+    "license": "LGPL-3",
+}

encoach_core/data/assign_admin_group.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <record id="base.user_admin" model="res.users" context="{'no_reset_password': True}">
+        <field name="group_ids" eval="[
+            (4, ref('encoach_core.group_encoach_developer')),
+        ]"/>
+    </record>
+</odoo>

encoach_core/data/constants.xml

@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <data noupdate="1">
+        <!-- JWT signing secret -->
+        <record id="param_jwt_secret" model="ir.config_parameter">
+            <field name="key">encoach.jwt_secret</field>
+            <field name="value">CHANGE_ME_IN_PRODUCTION_RANDOM_256_BIT_STRING</field>
+        </record>
+        <record id="param_jwt_expiry_hours" model="ir.config_parameter">
+            <field name="key">encoach.jwt_expiry_hours</field>
+            <field name="value">72</field>
+        </record>
+
+        <!-- AI service keys (placeholders) -->
+        <record id="param_openai_key" model="ir.config_parameter">
+            <field name="key">encoach.openai_api_key</field>
+            <field name="value"></field>
+        </record>
+        <record id="param_aws_access_key" model="ir.config_parameter">
+            <field name="key">encoach.aws_access_key_id</field>
+            <field name="value"></field>
+        </record>
+        <record id="param_aws_secret_key" model="ir.config_parameter">
+            <field name="key">encoach.aws_secret_access_key</field>
+            <field name="value"></field>
+        </record>
+        <record id="param_elai_token" model="ir.config_parameter">
+            <field name="key">encoach.elai_token</field>
+            <field name="value"></field>
+        </record>
+        <record id="param_gptzero_key" model="ir.config_parameter">
+            <field name="key">encoach.gptzero_api_key</field>
+            <field name="value"></field>
+        </record>
+        <record id="param_stripe_secret" model="ir.config_parameter">
+            <field name="key">encoach.stripe_secret_key</field>
+            <field name="value"></field>
+        </record>
+        <record id="param_stripe_webhook" model="ir.config_parameter">
+            <field name="key">encoach.stripe_webhook_secret</field>
+            <field name="value"></field>
+        </record>
+        <record id="param_paypal_client" model="ir.config_parameter">
+            <field name="key">encoach.paypal_client_id</field>
+            <field name="value"></field>
+        </record>
+        <record id="param_paypal_secret" model="ir.config_parameter">
+            <field name="key">encoach.paypal_client_secret</field>
+            <field name="value"></field>
+        </record>
+        <record id="param_paymob_key" model="ir.config_parameter">
+            <field name="key">encoach.paymob_api_key</field>
+            <field name="value"></field>
+        </record>
+    </data>
+</odoo>

encoach_core/models/__init__.py

@@ -0,0 +1,7 @@
+from . import res_users
+from . import entity
+from . import role
+from . import permission
+from . import code
+from . import invite
+from . import user_entity_rel

encoach_core/models/code.py

@@ -0,0 +1,57 @@
+import uuid
+from odoo import models, fields, api
+
+
+class EncoachCode(models.Model):
+    _name = "encoach.code"
+    _description = "EnCoach Registration Code"
+
+    code = fields.Char(required=True, index=True, default=lambda self: uuid.uuid4().hex[:8].upper())
+    entity_id = fields.Many2one("encoach.entity", ondelete="set null")
+    creator_id = fields.Many2one("res.users", required=True)
+    expiry_date = fields.Datetime()
+    code_type = fields.Selection(
+        [("individual", "Individual"), ("corporate", "Corporate")],
+        default="individual",
+    )
+    max_uses = fields.Integer(default=1)
+    uses = fields.Integer(default=0)
+    user_type = fields.Selection(
+        [
+            ("student", "Student"),
+            ("teacher", "Teacher"),
+            ("corporate", "Corporate"),
+        ],
+        default="student",
+    )
+    legacy_id = fields.Char(index=True)
+
+    @api.model
+    def validate_code(self, code_str):
+        rec = self.search([("code", "=", code_str)], limit=1)
+        if not rec:
+            return {"valid": False, "error": "Code not found"}
+        if rec.expiry_date and rec.expiry_date < fields.Datetime.now():
+            return {"valid": False, "error": "Code expired"}
+        if rec.max_uses and rec.uses >= rec.max_uses:
+            return {"valid": False, "error": "Code fully used"}
+        return {
+            "valid": True,
+            "code": rec.to_encoach_dict(),
+        }
+
+    def to_encoach_dict(self):
+        self.ensure_one()
+        return {
+            "id": self.id,
+            "code": self.code,
+            "entity": self.entity_id.id if self.entity_id else None,
+            "creator": self.creator_id.id,
+            "expiryDate": (
+                self.expiry_date.isoformat() if self.expiry_date else None
+            ),
+            "type": self.code_type,
+            "maxUses": self.max_uses,
+            "uses": self.uses,
+            "userType": self.user_type,
+        }

encoach_core/models/entity.py

@@ -0,0 +1,37 @@
+from odoo import models, fields
+
+
+class EncoachEntity(models.Model):
+    _name = "encoach.entity"
+    _description = "EnCoach Entity (Organization)"
+    _inherit = ["mail.thread"]
+
+    name = fields.Char(required=True, tracking=True)
+    label = fields.Char()
+    licenses = fields.Integer(default=0)
+    expiry_date = fields.Datetime()
+    payment_currency = fields.Char()
+    payment_price = fields.Float(digits=(12, 2))
+    role_ids = fields.One2many("encoach.role", "entity_id", string="Roles")
+    user_rel_ids = fields.One2many(
+        "encoach.user.entity.rel", "entity_id", string="Members",
+    )
+    legacy_id = fields.Char(index=True)
+
+    def to_encoach_dict(self):
+        self.ensure_one()
+        payment = None
+        if self.payment_currency and self.payment_price:
+            payment = {
+                "currency": self.payment_currency,
+                "price": self.payment_price,
+            }
+        return {
+            "id": self.id,
+            "label": self.label or self.name,
+            "licenses": self.licenses,
+            "expiryDate": (
+                self.expiry_date.isoformat() if self.expiry_date else None
+            ),
+            "payment": payment,
+        }

encoach_core/models/invite.py

@@ -0,0 +1,46 @@
+from odoo import models, fields
+
+
+class EncoachInvite(models.Model):
+    _name = "encoach.invite"
+    _description = "EnCoach Entity Invite"
+
+    from_user_id = fields.Many2one("res.users", required=True, ondelete="cascade")
+    to_user_id = fields.Many2one("res.users", required=True, ondelete="cascade")
+    entity_id = fields.Many2one("encoach.entity", required=True, ondelete="cascade")
+    status = fields.Selection(
+        [
+            ("pending", "Pending"),
+            ("accepted", "Accepted"),
+            ("declined", "Declined"),
+        ],
+        default="pending",
+    )
+    legacy_id = fields.Char(index=True)
+
+    def action_accept(self):
+        self.ensure_one()
+        self.status = "accepted"
+        existing = self.env["encoach.user.entity.rel"].search([
+            ("user_id", "=", self.to_user_id.id),
+            ("entity_id", "=", self.entity_id.id),
+        ], limit=1)
+        if not existing:
+            self.env["encoach.user.entity.rel"].create({
+                "user_id": self.to_user_id.id,
+                "entity_id": self.entity_id.id,
+            })
+
+    def action_decline(self):
+        self.ensure_one()
+        self.status = "declined"
+
+    def to_encoach_dict(self):
+        self.ensure_one()
+        return {
+            "id": self.id,
+            "from": self.from_user_id.id,
+            "to": self.to_user_id.id,
+            "entity": self.entity_id.id,
+            "status": self.status,
+        }

encoach_core/models/permission.py

@@ -0,0 +1,45 @@
+from odoo import models, fields
+
+PERMISSION_TOPICS = [
+    ("exam", "Exam Management"),
+    ("user", "User Management"),
+    ("entity", "Entity Management"),
+    ("group", "Group Management"),
+    ("assignment", "Assignment Management"),
+    ("code", "Code Management"),
+    ("invite", "Invite Management"),
+    ("payment", "Payment Management"),
+    ("ticket", "Ticket Management"),
+    ("approval", "Approval Workflow"),
+    ("stats", "Statistics"),
+    ("training", "Training"),
+]
+
+PERMISSION_TYPES = [
+    ("create", "Create"),
+    ("read", "Read"),
+    ("update", "Update"),
+    ("delete", "Delete"),
+]
+
+
+class EncoachPermission(models.Model):
+    _name = "encoach.permission"
+    _description = "EnCoach Permission"
+
+    topic = fields.Selection(PERMISSION_TOPICS, required=True)
+    perm_type = fields.Selection(PERMISSION_TYPES, required=True)
+    legacy_id = fields.Char(index=True)
+
+    _topic_type_unique = models.Constraint(
+        "UNIQUE(topic, perm_type)",
+        "Permission topic/type combination must be unique.",
+    )
+
+    def to_encoach_dict(self):
+        self.ensure_one()
+        return {
+            "id": self.id,
+            "topic": self.topic,
+            "type": self.perm_type,
+        }

encoach_core/models/res_users.py

@@ -0,0 +1,92 @@
+from odoo import models, fields, api
+
+USER_TYPES = [
+    ("student", "Student"),
+    ("teacher", "Teacher"),
+    ("corporate", "Corporate"),
+    ("admin", "Admin"),
+    ("developer", "Developer"),
+    ("agent", "Agent"),
+    ("mastercorporate", "Master Corporate"),
+]
+
+DEFAULT_LEVELS = {"reading": 0, "listening": 0, "writing": 0, "speaking": 0}
+
+
+class ResUsers(models.Model):
+    _inherit = "res.users"
+
+    encoach_type = fields.Selection(
+        USER_TYPES, string="EnCoach User Type", default="student",
+    )
+    focus = fields.Char()
+    levels = fields.Json(default=DEFAULT_LEVELS)
+    desired_levels = fields.Json(default=DEFAULT_LEVELS)
+    is_verified = fields.Boolean(default=False)
+    subscription_expiration = fields.Datetime()
+    registration_date = fields.Datetime(default=fields.Datetime.now)
+    bio = fields.Text()
+    profile_picture = fields.Char()
+    is_first_login = fields.Boolean(default=True)
+    last_login = fields.Datetime()
+    encoach_status = fields.Selection(
+        [("active", "Active"), ("inactive", "Inactive"), ("suspended", "Suspended")],
+        string="EnCoach Status",
+        default="active",
+    )
+    entity_rel_ids = fields.One2many(
+        "encoach.user.entity.rel", "user_id", string="Entity Memberships",
+    )
+    legacy_id = fields.Char(index=True)
+
+    def to_encoach_dict(self):
+        """Serialize to the JSON shape the frontend expects."""
+        self.ensure_one()
+        entities = []
+        for rel in self.entity_rel_ids:
+            entities.append({
+                "id": rel.entity_id.id,
+                "role": rel.role_id.name if rel.role_id else None,
+            })
+        return {
+            "id": self.id,
+            "email": self.login,
+            "name": self.name,
+            "profilePicture": self.profile_picture or "",
+            "isFirstLogin": self.is_first_login,
+            "focus": self.focus or "",
+            "levels": self.levels or DEFAULT_LEVELS,
+            "desiredLevels": self.desired_levels or DEFAULT_LEVELS,
+            "type": self.encoach_type,
+            "bio": self.bio or "",
+            "isVerified": self.is_verified,
+            "subscriptionExpirationDate": (
+                self.subscription_expiration.isoformat()
+                if self.subscription_expiration
+                else None
+            ),
+            "registrationDate": (
+                self.registration_date.isoformat()
+                if self.registration_date
+                else None
+            ),
+            "status": self.encoach_status,
+            "lastLogin": (
+                self.last_login.isoformat() if self.last_login else None
+            ),
+            "entities": entities,
+            "permissions": self._get_encoach_permissions(),
+        }
+
+    def _get_encoach_permissions(self):
+        self.ensure_one()
+        perms = {}
+        for rel in self.entity_rel_ids:
+            if rel.role_id:
+                for perm in rel.role_id.permission_ids:
+                    key = perm.topic
+                    if key not in perms:
+                        perms[key] = []
+                    if perm.perm_type not in perms[key]:
+                        perms[key].append(perm.perm_type)
+        return perms

encoach_core/models/role.py

@@ -0,0 +1,20 @@
+from odoo import models, fields
+
+
+class EncoachRole(models.Model):
+    _name = "encoach.role"
+    _description = "EnCoach Role"
+
+    name = fields.Char(required=True)
+    entity_id = fields.Many2one("encoach.entity", required=True, ondelete="cascade")
+    permission_ids = fields.Many2many("encoach.permission", string="Permissions")
+    legacy_id = fields.Char(index=True)
+
+    def to_encoach_dict(self):
+        self.ensure_one()
+        return {
+            "id": self.id,
+            "name": self.name,
+            "entity": self.entity_id.id,
+            "permissions": [p.to_encoach_dict() for p in self.permission_ids],
+        }

encoach_core/models/user_entity_rel.py

@@ -0,0 +1,15 @@
+from odoo import models, fields
+
+
+class EncoachUserEntityRel(models.Model):
+    _name = "encoach.user.entity.rel"
+    _description = "EnCoach User-Entity Membership"
+
+    user_id = fields.Many2one("res.users", required=True, ondelete="cascade")
+    entity_id = fields.Many2one("encoach.entity", required=True, ondelete="cascade")
+    role_id = fields.Many2one("encoach.role", ondelete="set null")
+
+    _user_entity_unique = models.Constraint(
+        "UNIQUE(user_id, entity_id)",
+        "A user can only have one membership per entity.",
+    )

encoach_core/scripts/import_avatars.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""
+Import ELAI avatars from avatars.json into encoach.elai.avatar.
+
+Usage (Odoo shell):
+    ./odoo-bin shell -c odoo.conf -d encoach_prod
+    >>> exec(open('../addons_extra/encoach_core/scripts/import_avatars.py').read())
+"""
+import json
+import logging
+import os
+
+_logger = logging.getLogger("encoach.avatar_import")
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+
+AVATARS_JSON = os.path.join(
+    os.path.dirname(__file__), "..", "..", "encoach", "encoach_backend", "elai", "avatars.json"
+)
+
+
+def import_avatars(env, json_path=None):
+    path = json_path or AVATARS_JSON
+    if not os.path.exists(path):
+        _logger.error("avatars.json not found at %s", path)
+        return
+
+    with open(path, "r") as f:
+        avatars = json.load(f)
+
+    if isinstance(avatars, dict):
+        avatars = list(avatars.values())
+
+    created = 0
+    skipped = 0
+
+    for av in avatars:
+        code = av.get("code", av.get("avatar_code", ""))
+        if not code:
+            skipped += 1
+            continue
+
+        existing = env["encoach.elai.avatar"].sudo().search([("avatar_code", "=", code)], limit=1)
+        if existing:
+            skipped += 1
+            continue
+
+        voice = av.get("voice", {})
+        voice_id = voice.get("voiceId") if isinstance(voice, dict) else av.get("voice_id")
+        voice_provider = voice.get("voiceProvider") if isinstance(voice, dict) else av.get("voice_provider")
+
+        env["encoach.elai.avatar"].sudo().create({
+            "name": av.get("name", code),
+            "avatar_code": code,
+            "avatar_url": av.get("url", av.get("avatar_url", "")),
+            "gender": av.get("gender"),
+            "canvas": av.get("canvas"),
+            "voice_id": voice_id,
+            "voice_provider": voice_provider,
+        })
+        created += 1
+
+    _logger.info("Avatar import complete: created=%d, skipped=%d", created, skipped)
+
+
+try:
+    env  # noqa: F821
+    import_avatars(env)
+except NameError:
+    _logger.info("Run this script inside Odoo shell")

encoach_core/scripts/migrate_firebase_auth.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""
+Firebase Auth -> Odoo res.users migration script.
+
+Exports users from Firebase Auth (via Admin SDK) and creates/updates
+corresponding Odoo res.users records with EnCoach extensions.
+
+Usage (Odoo shell):
+    ./odoo-bin shell -c odoo.conf -d encoach_prod
+    >>> exec(open('../addons_extra/encoach_core/scripts/migrate_firebase_auth.py').read())
+
+Requires: firebase-admin
+    pip install firebase-admin
+"""
+import logging
+
+_logger = logging.getLogger("encoach.firebase_migration")
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+
+try:
+    import firebase_admin
+    from firebase_admin import auth as fb_auth, credentials
+except ImportError:
+    _logger.error("firebase-admin is required: pip install firebase-admin")
+    firebase_admin = None
+
+
+SERVICE_ACCOUNT_PATH = "serviceAccountKey.json"
+
+
+def migrate_firebase_users(env, service_account_path=SERVICE_ACCOUNT_PATH):
+    if not firebase_admin:
+        _logger.error("firebase-admin not installed")
+        return
+
+    cred = credentials.Certificate(service_account_path)
+    try:
+        firebase_admin.get_app()
+    except ValueError:
+        firebase_admin.initialize_app(cred)
+
+    _logger.info("Fetching Firebase users...")
+
+    created = 0
+    updated = 0
+    skipped = 0
+    errors = 0
+
+    page = fb_auth.list_users()
+    while page:
+        for fb_user in page.users:
+            email = fb_user.email
+            if not email:
+                skipped += 1
+                continue
+            try:
+                existing = env["res.users"].sudo().search([("login", "=", email)], limit=1)
+                if existing:
+                    vals = {}
+                    if fb_user.display_name and not existing.name:
+                        vals["name"] = fb_user.display_name
+                    if fb_user.email_verified and not existing.is_verified:
+                        vals["is_verified"] = True
+                    if fb_user.photo_url and not existing.profile_picture:
+                        vals["profile_picture"] = fb_user.photo_url
+                    if vals:
+                        existing.sudo().write(vals)
+                        updated += 1
+                    else:
+                        skipped += 1
+                else:
+                    env["res.users"].sudo().create({
+                        "login": email,
+                        "name": fb_user.display_name or email.split("@")[0],
+                        "password": "changeme_firebase_migrated",
+                        "encoach_type": "student",
+                        "is_verified": fb_user.email_verified,
+                        "profile_picture": fb_user.photo_url or "",
+                        "legacy_id": fb_user.uid,
+                    })
+                    created += 1
+            except Exception as e:
+                _logger.error("Error migrating %s: %s", email, e)
+                errors += 1
+
+        page = page.get_next_page()
+
+    _logger.info(
+        "Firebase migration complete: created=%d, updated=%d, skipped=%d, errors=%d",
+        created, updated, skipped, errors,
+    )
+
+
+try:
+    env  # noqa: F821
+    migrate_firebase_users(env)
+except NameError:
+    _logger.info("Run this script inside Odoo shell")

encoach_core/scripts/migrate_mongodb.py

@@ -0,0 +1,731 @@
+#!/usr/bin/env python3
+"""
+MongoDB -> Odoo PostgreSQL data migration script.
+
+Usage (from Odoo shell):
+    ./odoo-bin shell -c odoo.conf -d encoach_prod
+    >>> exec(open('../addons_extra/encoach_core/scripts/migrate_mongodb.py').read())
+
+Or standalone:
+    python migrate_mongodb.py --mongo-uri mongodb://localhost:27017 --mongo-db encoach --odoo-url http://localhost:8069 --odoo-db encoach_prod
+
+Requires: pymongo, xmlrpc.client (stdlib)
+"""
+import argparse
+import logging
+import sys
+from datetime import datetime
+
+_logger = logging.getLogger("encoach.migration")
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+
+try:
+    from pymongo import MongoClient
+except ImportError:
+    _logger.error("pymongo is required: pip install pymongo")
+    sys.exit(1)
+
+COLLECTION_MAP = {
+    "users":        "res.users",
+    "entities":     "encoach.entity",
+    "roles":        "encoach.role",
+    "permissions":  "encoach.permission",
+    "codes":        "encoach.code",
+    "invites":      "encoach.invite",
+    "exams":        "encoach.exam",
+    "groups":       "encoach.group",
+    "assignments":  "encoach.assignment",
+    "sessions":     "encoach.session",
+    "stats":        "encoach.stat",
+    "evaluations":  "encoach.evaluation",
+    "trainings":    "encoach.training",
+    "tips":         "encoach.training.tip",
+    "walkthroughs": "encoach.walkthrough",
+    "packages":     "encoach.package",
+    "payments":     "encoach.subscription.payment",
+    "discounts":    "encoach.discount",
+    "tickets":      "encoach.ticket",
+    "avatars":      "encoach.elai.avatar",
+}
+
+LEGACY_ID_CACHE = {}
+
+
+def _oid(doc, key="_id"):
+    val = doc.get(key)
+    if val is None:
+        return None
+    return str(val)
+
+
+def _dt(val):
+    if isinstance(val, datetime):
+        return val.strftime("%Y-%m-%d %H:%M:%S")
+    if isinstance(val, str):
+        return val
+    if isinstance(val, (int, float)):
+        return datetime.fromtimestamp(val / 1000).strftime("%Y-%m-%d %H:%M:%S")
+    return None
+
+
+def _resolve_legacy(model, legacy_id, env):
+    """Look up Odoo record ID by legacy MongoDB _id."""
+    if not legacy_id:
+        return False
+    cache_key = (model, str(legacy_id))
+    if cache_key in LEGACY_ID_CACHE:
+        return LEGACY_ID_CACHE[cache_key]
+    rec = env[model].sudo().search([("legacy_id", "=", str(legacy_id))], limit=1)
+    if rec:
+        LEGACY_ID_CACHE[cache_key] = rec.id
+        return rec.id
+    return False
+
+
+class EncoachMigrator:
+
+    def __init__(self, mongo_uri, mongo_db, env):
+        self.client = MongoClient(mongo_uri)
+        self.db = self.client[mongo_db]
+        self.env = env
+        self.stats = {k: {"total": 0, "created": 0, "skipped": 0, "error": 0} for k in COLLECTION_MAP}
+
+    def run(self):
+        _logger.info("Starting EnCoach data migration")
+        self._migrate_entities()
+        self._migrate_permissions()
+        self._migrate_roles()
+        self._migrate_users()
+        self._migrate_codes()
+        self._migrate_invites()
+        self._migrate_exams()
+        self._migrate_groups()
+        self._migrate_assignments()
+        self._migrate_sessions()
+        self._migrate_stats()
+        self._migrate_evaluations()
+        self._migrate_trainings()
+        self._migrate_tips()
+        self._migrate_walkthroughs()
+        self._migrate_packages()
+        self._migrate_payments()
+        self._migrate_discounts()
+        self._migrate_tickets()
+        self._migrate_avatars()
+        self._print_summary()
+
+    def _migrate_entities(self):
+        coll = "entities"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.entity"].sudo().search([("legacy_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                payment = doc.get("payment", {}) or {}
+                rec = self.env["encoach.entity"].sudo().create({
+                    "name": doc.get("label", doc.get("name", "Unknown")),
+                    "label": doc.get("label"),
+                    "licenses": doc.get("licenses", 0),
+                    "expiry_date": _dt(doc.get("expiryDate")),
+                    "payment_currency": payment.get("currency"),
+                    "payment_price": payment.get("price", 0),
+                    "legacy_id": lid,
+                })
+                LEGACY_ID_CACHE[("encoach.entity", lid)] = rec.id
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Entity %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_permissions(self):
+        coll = "permissions"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.permission"].sudo().search([("legacy_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                rec = self.env["encoach.permission"].sudo().create({
+                    "topic": doc.get("topic", "exam"),
+                    "perm_type": doc.get("type", "read"),
+                    "legacy_id": lid,
+                })
+                LEGACY_ID_CACHE[("encoach.permission", lid)] = rec.id
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Permission %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_roles(self):
+        coll = "roles"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.role"].sudo().search([("legacy_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                entity_id = _resolve_legacy("encoach.entity", doc.get("entity"), self.env)
+                perm_ids = []
+                for pid in doc.get("permissions", []):
+                    odoo_id = _resolve_legacy("encoach.permission", str(pid), self.env)
+                    if odoo_id:
+                        perm_ids.append(odoo_id)
+                rec = self.env["encoach.role"].sudo().create({
+                    "name": doc.get("name", "Unknown"),
+                    "entity_id": entity_id or False,
+                    "permission_ids": [(6, 0, perm_ids)],
+                    "legacy_id": lid,
+                })
+                LEGACY_ID_CACHE[("encoach.role", lid)] = rec.id
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Role %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_users(self):
+        coll = "users"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            email = doc.get("email", "")
+            if not email:
+                self.stats[coll]["skipped"] += 1
+                continue
+            existing = self.env["res.users"].sudo().search([
+                "|", ("login", "=", email), ("legacy_id", "=", lid),
+            ], limit=1)
+            if existing:
+                if not existing.legacy_id:
+                    existing.sudo().write({"legacy_id": lid})
+                LEGACY_ID_CACHE[("res.users", lid)] = existing.id
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                vals = {
+                    "login": email,
+                    "name": doc.get("name", email.split("@")[0]),
+                    "password": "changeme_migrated",
+                    "encoach_type": doc.get("type", "student"),
+                    "focus": doc.get("focus"),
+                    "levels": doc.get("levels"),
+                    "desired_levels": doc.get("desiredLevels"),
+                    "is_verified": doc.get("isVerified", False),
+                    "bio": doc.get("bio"),
+                    "profile_picture": doc.get("profilePicture"),
+                    "registration_date": _dt(doc.get("registrationDate")),
+                    "subscription_expiration": _dt(doc.get("subscriptionExpirationDate")),
+                    "legacy_id": lid,
+                }
+                rec = self.env["res.users"].sudo().create(vals)
+                LEGACY_ID_CACHE[("res.users", lid)] = rec.id
+
+                for ent_info in doc.get("entities", []):
+                    ent_id = ent_info if isinstance(ent_info, str) else ent_info.get("id") if isinstance(ent_info, dict) else str(ent_info)
+                    entity_odoo = _resolve_legacy("encoach.entity", ent_id, self.env)
+                    if entity_odoo:
+                        role_id = None
+                        if isinstance(ent_info, dict) and ent_info.get("role"):
+                            role_id = _resolve_legacy("encoach.role", ent_info["role"], self.env)
+                        self.env["encoach.user.entity.rel"].sudo().create({
+                            "user_id": rec.id,
+                            "entity_id": entity_odoo,
+                            "role_id": role_id or False,
+                        })
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("User %s (%s): %s", lid, email, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_codes(self):
+        coll = "codes"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.code"].sudo().search([("legacy_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                creator_id = _resolve_legacy("res.users", doc.get("creator"), self.env)
+                entity_id = _resolve_legacy("encoach.entity", doc.get("entity"), self.env)
+                rec = self.env["encoach.code"].sudo().create({
+                    "code": doc.get("code", lid[:8]),
+                    "entity_id": entity_id or False,
+                    "creator_id": creator_id or self.env.ref("base.user_admin").id,
+                    "expiry_date": _dt(doc.get("expiryDate")),
+                    "code_type": doc.get("type", "individual"),
+                    "max_uses": doc.get("maxUses", 1),
+                    "uses": doc.get("uses", 0),
+                    "user_type": doc.get("userType", "student"),
+                    "legacy_id": lid,
+                })
+                LEGACY_ID_CACHE[("encoach.code", lid)] = rec.id
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Code %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_invites(self):
+        coll = "invites"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.invite"].sudo().search([("legacy_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                from_id = _resolve_legacy("res.users", doc.get("from"), self.env)
+                to_id = _resolve_legacy("res.users", doc.get("to"), self.env)
+                entity_id = _resolve_legacy("encoach.entity", doc.get("entity"), self.env)
+                if not (from_id and to_id and entity_id):
+                    self.stats[coll]["skipped"] += 1
+                    continue
+                rec = self.env["encoach.invite"].sudo().create({
+                    "from_user_id": from_id,
+                    "to_user_id": to_id,
+                    "entity_id": entity_id,
+                    "status": doc.get("status", "pending"),
+                    "legacy_id": lid,
+                })
+                LEGACY_ID_CACHE[("encoach.invite", lid)] = rec.id
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Invite %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_exams(self):
+        coll = "exams"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.exam"].sudo().search([("legacy_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                module = doc.get("module", "reading")
+                owner_ids = []
+                for oid in doc.get("owners", []):
+                    uid = _resolve_legacy("res.users", str(oid), self.env)
+                    if uid:
+                        owner_ids.append(uid)
+                entity_ids = []
+                for eid in doc.get("entities", []):
+                    e_id = _resolve_legacy("encoach.entity", str(eid), self.env)
+                    if e_id:
+                        entity_ids.append(e_id)
+                rec = self.env["encoach.exam"].sudo().create({
+                    "module": module,
+                    "min_timer": doc.get("minTimer", 0),
+                    "is_diagnostic": doc.get("isDiagnostic", False),
+                    "variant": doc.get("variant"),
+                    "difficulty": doc.get("difficulty"),
+                    "owner_ids": [(6, 0, owner_ids)],
+                    "entity_ids": [(6, 0, entity_ids)],
+                    "shuffle": doc.get("shuffle", False),
+                    "access": doc.get("access", "public"),
+                    "label": doc.get("label", ""),
+                    "requires_approval": doc.get("requiresApproval", False),
+                    "approved": doc.get("approved", False),
+                    "parts": doc.get("parts", []),
+                    "legacy_id": lid,
+                })
+                LEGACY_ID_CACHE[("encoach.exam", lid)] = rec.id
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Exam %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_groups(self):
+        coll = "groups"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.group"].sudo().search([("legacy_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                admin_id = _resolve_legacy("res.users", doc.get("admin"), self.env)
+                participant_ids = []
+                for pid in doc.get("participants", []):
+                    uid = _resolve_legacy("res.users", str(pid), self.env)
+                    if uid:
+                        participant_ids.append(uid)
+                entity_id = _resolve_legacy("encoach.entity", doc.get("entity"), self.env)
+                rec = self.env["encoach.group"].sudo().create({
+                    "name": doc.get("name", "Unnamed"),
+                    "admin_id": admin_id or self.env.ref("base.user_admin").id,
+                    "participant_ids": [(6, 0, participant_ids)],
+                    "disable_editing": doc.get("disableEditing", False),
+                    "entity_id": entity_id or False,
+                    "legacy_id": lid,
+                })
+                LEGACY_ID_CACHE[("encoach.group", lid)] = rec.id
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Group %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_assignments(self):
+        coll = "assignments"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.assignment"].sudo().search([("legacy_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                assigner_id = _resolve_legacy("res.users", doc.get("assigner"), self.env)
+                assignee_ids = [
+                    _resolve_legacy("res.users", str(a), self.env)
+                    for a in doc.get("assignees", [])
+                ]
+                assignee_ids = [a for a in assignee_ids if a]
+                exam_ids = [
+                    _resolve_legacy("encoach.exam", str(e), self.env)
+                    for e in doc.get("exams", [])
+                ]
+                exam_ids = [e for e in exam_ids if e]
+                teacher_ids = [
+                    _resolve_legacy("res.users", str(t), self.env)
+                    for t in doc.get("teachers", [])
+                ]
+                teacher_ids = [t for t in teacher_ids if t]
+                entity_id = _resolve_legacy("encoach.entity", doc.get("entity"), self.env)
+                rec = self.env["encoach.assignment"].sudo().create({
+                    "name": doc.get("name", "Unnamed"),
+                    "assigner_id": assigner_id or self.env.ref("base.user_admin").id,
+                    "assignee_ids": [(6, 0, assignee_ids)],
+                    "exam_ids": [(6, 0, exam_ids)],
+                    "results": doc.get("results"),
+                    "instructor_gender": doc.get("instructorGender"),
+                    "start_date": _dt(doc.get("startDate")),
+                    "end_date": _dt(doc.get("endDate")),
+                    "teacher_ids": [(6, 0, teacher_ids)],
+                    "archived": doc.get("archived", False),
+                    "released": doc.get("released", False),
+                    "started": doc.get("start", False),
+                    "auto_start": doc.get("autoStart", False),
+                    "entity_id": entity_id or False,
+                    "legacy_id": lid,
+                })
+                LEGACY_ID_CACHE[("encoach.assignment", lid)] = rec.id
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Assignment %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_sessions(self):
+        coll = "sessions"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.session"].sudo().search([("legacy_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                user_id = _resolve_legacy("res.users", doc.get("user"), self.env)
+                if not user_id:
+                    self.stats[coll]["skipped"] += 1
+                    continue
+                exam_data = {k: v for k, v in doc.items() if k not in ("_id", "user", "__v")}
+                rec = self.env["encoach.session"].sudo().create({
+                    "user_id": user_id,
+                    "exam_data": exam_data,
+                    "date": _dt(doc.get("date")) or _dt(doc.get("_id").generation_time) if hasattr(doc.get("_id"), "generation_time") else None,
+                    "legacy_id": lid,
+                })
+                LEGACY_ID_CACHE[("encoach.session", lid)] = rec.id
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Session %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_stats(self):
+        coll = "stats"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.stat"].sudo().search([("legacy_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                user_id = _resolve_legacy("res.users", doc.get("user"), self.env)
+                if not user_id:
+                    self.stats[coll]["skipped"] += 1
+                    continue
+                exam_id = _resolve_legacy("encoach.exam", doc.get("exam"), self.env)
+                session_id = _resolve_legacy("encoach.session", doc.get("session"), self.env)
+                assignment_id = _resolve_legacy("encoach.assignment", doc.get("assignment"), self.env)
+                score = doc.get("score", {})
+                rec = self.env["encoach.stat"].sudo().create({
+                    "user_id": user_id,
+                    "exam_id": exam_id or False,
+                    "exercise": doc.get("exercise"),
+                    "session_id": session_id or False,
+                    "date": _dt(doc.get("date")),
+                    "module": doc.get("module"),
+                    "solutions": doc.get("solutions"),
+                    "stat_type": doc.get("type"),
+                    "time_spent": doc.get("timeSpent", 0),
+                    "inactivity": doc.get("inactivity", 0),
+                    "assignment_id": assignment_id or False,
+                    "score_correct": score.get("correct", 0) if isinstance(score, dict) else 0,
+                    "score_total": score.get("total", 0) if isinstance(score, dict) else 0,
+                    "score_missing": score.get("missing", 0) if isinstance(score, dict) else 0,
+                    "is_disabled": doc.get("isDisabled", False),
+                    "shuffle_maps": doc.get("shuffleMaps"),
+                    "is_practice": doc.get("isPractice", False),
+                    "legacy_id": lid,
+                })
+                LEGACY_ID_CACHE[("encoach.stat", lid)] = rec.id
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Stat %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_evaluations(self):
+        coll = "evaluations"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.evaluation"].sudo().search([("legacy_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                user_id = _resolve_legacy("res.users", doc.get("user"), self.env)
+                rec = self.env["encoach.evaluation"].sudo().create({
+                    "user_id": user_id or False,
+                    "exercise_id": doc.get("exerciseId"),
+                    "exercise_type": doc.get("exerciseType"),
+                    "status": doc.get("status", "completed"),
+                    "result": doc.get("result"),
+                    "legacy_id": lid,
+                })
+                LEGACY_ID_CACHE[("encoach.evaluation", lid)] = rec.id
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Evaluation %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_trainings(self):
+        coll = "trainings"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.training"].sudo().search([("legacy_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                user_id = _resolve_legacy("res.users", doc.get("user"), self.env)
+                rec = self.env["encoach.training"].sudo().create({
+                    "user_id": user_id or self.env.ref("base.user_admin").id,
+                    "exams": doc.get("exams"),
+                    "tips": doc.get("tips"),
+                    "weak_areas": doc.get("weakAreas"),
+                    "legacy_id": lid,
+                })
+                LEGACY_ID_CACHE[("encoach.training", lid)] = rec.id
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Training %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_tips(self):
+        coll = "tips"
+        _logger.info("Migrating %s (from training.tip collection)...", coll)
+        for doc in self.db.get_collection("training_tips").find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.training.tip"].sudo().search([("tip_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                self.env["encoach.training.tip"].sudo().create({
+                    "tip_id": lid,
+                    "category": doc.get("category"),
+                    "content": doc.get("content", ""),
+                })
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Tip %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_walkthroughs(self):
+        coll = "walkthroughs"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            try:
+                self.env["encoach.walkthrough"].sudo().create({
+                    "name": doc.get("name", ""),
+                    "content": doc.get("content"),
+                    "module": doc.get("module"),
+                })
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Walkthrough: %s", e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_packages(self):
+        coll = "packages"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            try:
+                self.env["encoach.package"].sudo().create({
+                    "name": doc.get("name", "Package"),
+                    "price": doc.get("price", 0),
+                    "currency": doc.get("currency", "USD"),
+                    "duration_days": doc.get("duration", 30),
+                    "features": doc.get("features"),
+                    "active": doc.get("active", True),
+                })
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Package: %s", e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_payments(self):
+        coll = "payments"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            try:
+                user_id = _resolve_legacy("res.users", doc.get("user"), self.env)
+                entity_id = _resolve_legacy("encoach.entity", doc.get("entity"), self.env)
+                self.env["encoach.subscription.payment"].sudo().create({
+                    "user_id": user_id or False,
+                    "provider": doc.get("provider", "stripe"),
+                    "status": doc.get("status", "completed"),
+                    "amount": doc.get("amount", 0),
+                    "currency": doc.get("currency", "USD"),
+                    "transaction_id": doc.get("transactionId"),
+                    "entity_id": entity_id or False,
+                    "legacy_id": lid,
+                })
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Payment %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_discounts(self):
+        coll = "discounts"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            try:
+                self.env["encoach.discount"].sudo().create({
+                    "code": doc.get("code", ""),
+                    "percentage": doc.get("percentage", 0),
+                    "expiry_date": _dt(doc.get("expiryDate")),
+                    "max_uses": doc.get("maxUses", 0),
+                    "uses": doc.get("uses", 0),
+                })
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Discount: %s", e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_tickets(self):
+        coll = "tickets"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db[coll].find():
+            self.stats[coll]["total"] += 1
+            lid = _oid(doc)
+            if self.env["encoach.ticket"].sudo().search([("legacy_id", "=", lid)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                reporter = doc.get("reporter", {})
+                assigned_id = _resolve_legacy("res.users", doc.get("assignedTo"), self.env)
+                self.env["encoach.ticket"].sudo().create({
+                    "reporter_name": reporter.get("name") if isinstance(reporter, dict) else None,
+                    "reporter_email": reporter.get("email") if isinstance(reporter, dict) else None,
+                    "subject": doc.get("subject", ""),
+                    "description": doc.get("description", ""),
+                    "ticket_type": doc.get("type", "help"),
+                    "status": doc.get("status", "open"),
+                    "exam_information": doc.get("examInformation"),
+                    "assigned_to_id": assigned_id or False,
+                    "legacy_id": lid,
+                })
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Ticket %s: %s", lid, e)
+                self.stats[coll]["error"] += 1
+
+    def _migrate_avatars(self):
+        coll = "avatars"
+        _logger.info("Migrating %s...", coll)
+        for doc in self.db.get_collection("avatars").find():
+            self.stats[coll]["total"] += 1
+            code = doc.get("code", doc.get("avatar_code", ""))
+            if self.env["encoach.elai.avatar"].sudo().search([("avatar_code", "=", code)], limit=1):
+                self.stats[coll]["skipped"] += 1
+                continue
+            try:
+                self.env["encoach.elai.avatar"].sudo().create({
+                    "name": doc.get("name", code),
+                    "avatar_code": code,
+                    "avatar_url": doc.get("url", doc.get("avatar_url", "")),
+                    "gender": doc.get("gender"),
+                    "canvas": doc.get("canvas"),
+                    "voice_id": doc.get("voice", {}).get("voiceId") if isinstance(doc.get("voice"), dict) else doc.get("voice_id"),
+                    "voice_provider": doc.get("voice", {}).get("voiceProvider") if isinstance(doc.get("voice"), dict) else doc.get("voice_provider"),
+                })
+                self.stats[coll]["created"] += 1
+            except Exception as e:
+                _logger.error("Avatar %s: %s", code, e)
+                self.stats[coll]["error"] += 1
+
+    def _print_summary(self):
+        _logger.info("\n========== MIGRATION SUMMARY ==========")
+        total_created = 0
+        total_skipped = 0
+        total_errors = 0
+        for coll, s in self.stats.items():
+            _logger.info(
+                "  %-15s  total=%4d  created=%4d  skipped=%4d  errors=%4d",
+                coll, s["total"], s["created"], s["skipped"], s["error"],
+            )
+            total_created += s["created"]
+            total_skipped += s["skipped"]
+            total_errors += s["error"]
+        _logger.info("  %-15s  total=%4d  created=%4d  skipped=%4d  errors=%4d",
+                      "TOTAL", total_created + total_skipped + total_errors,
+                      total_created, total_skipped, total_errors)
+        _logger.info("========================================\n")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Migrate EnCoach MongoDB to Odoo")
+    parser.add_argument("--mongo-uri", default="mongodb://localhost:27017")
+    parser.add_argument("--mongo-db", default="encoach")
+    args = parser.parse_args()
+    _logger.info("Standalone mode -- connect to Odoo via xmlrpc or run inside Odoo shell")
+    _logger.info("Example: ./odoo-bin shell -c odoo.conf -d encoach_prod")
+    _logger.info("Then: exec(open('path/to/migrate_mongodb.py').read())")
+else:
+    try:
+        env  # noqa: F821 -- available in Odoo shell
+        migrator = EncoachMigrator("mongodb://localhost:27017", "encoach", env)
+        migrator.run()
+    except NameError:
+        pass

encoach_core/scripts/rebuild_faiss.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""
+Rebuild FAISS indices for EnCoach training tips.
+
+After data migration, this script re-embeds all training tips using
+sentence-transformers and builds per-category FAISS indices.
+
+Usage (Odoo shell):
+    ./odoo-bin shell -c odoo.conf -d encoach_prod
+    >>> exec(open('../addons_extra/encoach_core/scripts/rebuild_faiss.py').read())
+
+Requires: faiss-cpu, sentence-transformers
+"""
+import logging
+import os
+import pickle
+
+import numpy as np
+
+_logger = logging.getLogger("encoach.faiss_rebuild")
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+
+try:
+    import faiss
+    from sentence_transformers import SentenceTransformer
+except ImportError:
+    _logger.error("Install: pip install faiss-cpu sentence-transformers")
+    faiss = None
+
+MODEL_NAME = "sentence-transformers/all-MiniLM-L6-v2"
+EMBEDDING_DIM = 384
+FAISS_DIR = os.path.join(os.path.dirname(__file__), "..", "..", "encoach_training", "data", "faiss")
+
+CATEGORIES = [
+    "ct_focus",
+    "language_for_writing",
+    "reading_skill",
+    "strategy",
+    "writing_skill",
+    "word_link",
+    "word_partners",
+]
+
+
+def rebuild_faiss_indices(env, output_dir=None):
+    if not faiss:
+        return
+
+    output_dir = output_dir or FAISS_DIR
+    os.makedirs(output_dir, exist_ok=True)
+
+    _logger.info("Loading sentence-transformers model: %s", MODEL_NAME)
+    model = SentenceTransformer(MODEL_NAME)
+
+    for category in CATEGORIES:
+        tips = env["encoach.training.tip"].sudo().search([("category", "=", category)])
+        if not tips:
+            _logger.info("  %s: no tips, skipping", category)
+            continue
+
+        contents = [t.content for t in tips]
+        tip_ids = [t.tip_id for t in tips]
+        _logger.info("  %s: encoding %d tips...", category, len(contents))
+
+        embeddings = model.encode(contents, show_progress_bar=False, convert_to_numpy=True)
+        embeddings = embeddings.astype(np.float32)
+
+        for tip, emb in zip(tips, embeddings):
+            tip.sudo().write({"embedding": pickle.dumps(emb)})
+
+        index = faiss.IndexFlatL2(EMBEDDING_DIM)
+        index.add(embeddings)
+
+        index_path = os.path.join(output_dir, f"{category}.index")
+        faiss.write_index(index, index_path)
+
+        ids_path = os.path.join(output_dir, f"{category}_ids.pkl")
+        with open(ids_path, "wb") as f:
+            pickle.dump(tip_ids, f)
+
+        _logger.info("  %s: indexed %d tips -> %s", category, len(tips), index_path)
+
+    _logger.info("FAISS rebuild complete. Indices saved to %s", output_dir)
+
+
+try:
+    env  # noqa: F821
+    rebuild_faiss_indices(env)
+except NameError:
+    _logger.info("Run this script inside Odoo shell")

encoach_core/security/ir.model.access.csv

@@ -0,0 +1,21 @@
+id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
+access_encoach_entity_student,encoach.entity.student,model_encoach_entity,group_encoach_student,1,0,0,0
+access_encoach_entity_admin,encoach.entity.admin,model_encoach_entity,group_encoach_admin,1,1,1,1
+access_encoach_role_student,encoach.role.student,model_encoach_role,group_encoach_student,1,0,0,0
+access_encoach_role_admin,encoach.role.admin,model_encoach_role,group_encoach_admin,1,1,1,1
+access_encoach_permission_student,encoach.permission.student,model_encoach_permission,group_encoach_student,1,0,0,0
+access_encoach_permission_admin,encoach.permission.admin,model_encoach_permission,group_encoach_admin,1,1,1,1
+access_encoach_code_student,encoach.code.student,model_encoach_code,group_encoach_student,1,0,0,0
+access_encoach_code_teacher,encoach.code.teacher,model_encoach_code,group_encoach_teacher,1,1,1,0
+access_encoach_code_admin,encoach.code.admin,model_encoach_code,group_encoach_admin,1,1,1,1
+access_encoach_invite_student,encoach.invite.student,model_encoach_invite,group_encoach_student,1,1,0,0
+access_encoach_invite_teacher,encoach.invite.teacher,model_encoach_invite,group_encoach_teacher,1,1,1,0
+access_encoach_invite_admin,encoach.invite.admin,model_encoach_invite,group_encoach_admin,1,1,1,1
+access_encoach_user_entity_rel_student,encoach.user.entity.rel.student,model_encoach_user_entity_rel,group_encoach_student,1,0,0,0
+access_encoach_user_entity_rel_admin,encoach.user.entity.rel.admin,model_encoach_user_entity_rel,group_encoach_admin,1,1,1,1
+access_encoach_entity_sysadmin,encoach.entity.sysadmin,model_encoach_entity,base.group_system,1,1,1,1
+access_encoach_role_sysadmin,encoach.role.sysadmin,model_encoach_role,base.group_system,1,1,1,1
+access_encoach_permission_sysadmin,encoach.permission.sysadmin,model_encoach_permission,base.group_system,1,1,1,1
+access_encoach_code_sysadmin,encoach.code.sysadmin,model_encoach_code,base.group_system,1,1,1,1
+access_encoach_invite_sysadmin,encoach.invite.sysadmin,model_encoach_invite,base.group_system,1,1,1,1
+access_encoach_user_entity_rel_sysadmin,encoach.user.entity.rel.sysadmin,model_encoach_user_entity_rel,base.group_system,1,1,1,1

encoach_core/security/security.xml

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <data noupdate="1">
+        <!-- Security groups matching the 7 user types -->
+        <record id="group_encoach_student" model="res.groups">
+            <field name="name">EnCoach Student</field>
+        </record>
+        <record id="group_encoach_teacher" model="res.groups">
+            <field name="name">EnCoach Teacher</field>
+        </record>
+        <record id="group_encoach_corporate" model="res.groups">
+            <field name="name">EnCoach Corporate</field>
+        </record>
+        <record id="group_encoach_admin" model="res.groups">
+            <field name="name">EnCoach Admin</field>
+            <field name="implied_ids" eval="[(4, ref('group_encoach_teacher'))]"/>
+        </record>
+        <record id="group_encoach_developer" model="res.groups">
+            <field name="name">EnCoach Developer</field>
+            <field name="implied_ids" eval="[(4, ref('group_encoach_admin'))]"/>
+        </record>
+        <record id="group_encoach_agent" model="res.groups">
+            <field name="name">EnCoach Agent</field>
+        </record>
+        <record id="group_encoach_mastercorporate" model="res.groups">
+            <field name="name">EnCoach Master Corporate</field>
+            <field name="implied_ids" eval="[(4, ref('group_encoach_corporate'))]"/>
+        </record>
+    </data>
+</odoo>

encoach_core/views/code_views.xml

@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <record id="view_encoach_code_tree" model="ir.ui.view">
+        <field name="name">encoach.code.tree</field>
+        <field name="model">encoach.code</field>
+        <field name="arch" type="xml">
+            <list string="Registration Codes" editable="bottom">
+                <field name="code"/>
+                <field name="entity_id"/>
+                <field name="creator_id"/>
+                <field name="code_type"/>
+                <field name="user_type"/>
+                <field name="max_uses"/>
+                <field name="uses"/>
+                <field name="expiry_date"/>
+            </list>
+        </field>
+    </record>
+
+    <record id="view_encoach_code_form" model="ir.ui.view">
+        <field name="name">encoach.code.form</field>
+        <field name="model">encoach.code</field>
+        <field name="arch" type="xml">
+            <form string="Registration Code">
+                <sheet>
+                    <group>
+                        <group>
+                            <field name="code" readonly="id"/>
+                            <field name="entity_id"/>
+                            <field name="creator_id"/>
+                            <field name="expiry_date"/>
+                        </group>
+                        <group>
+                            <field name="code_type"/>
+                            <field name="user_type"/>
+                            <field name="max_uses"/>
+                            <field name="uses"/>
+                        </group>
+                    </group>
+                </sheet>
+            </form>
+        </field>
+    </record>
+
+    <record id="action_encoach_code" model="ir.actions.act_window">
+        <field name="name">Registration Codes</field>
+        <field name="res_model">encoach.code</field>
+        <field name="view_mode">list,form</field>
+        <field name="help" type="html">
+            <p class="o_view_nocontent_smiling_face">
+                Create your first registration code.
+            </p>
+            <p>
+                Registration codes allow users to join entities or register
+                with a specific user type.
+            </p>
+        </field>
+    </record>
+
+    <menuitem id="menu_encoach_code"
+        name="Registration Codes"
+        parent="encoach_core.menu_encoach_users"
+        action="action_encoach_code"
+        sequence="20"/>
+</odoo>

encoach_core/views/entity_views.xml

@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <record id="view_encoach_entity_tree" model="ir.ui.view">
+        <field name="name">encoach.entity.tree</field>
+        <field name="model">encoach.entity</field>
+        <field name="arch" type="xml">
+            <list string="Entities" editable="bottom">
+                <field name="name"/>
+                <field name="label"/>
+                <field name="licenses"/>
+                <field name="expiry_date"/>
+                <field name="payment_currency"/>
+                <field name="payment_price"/>
+            </list>
+        </field>
+    </record>
+
+    <record id="view_encoach_entity_form" model="ir.ui.view">
+        <field name="name">encoach.entity.form</field>
+        <field name="model">encoach.entity</field>
+        <field name="arch" type="xml">
+            <form string="Entity">
+                <sheet>
+                    <group>
+                        <group>
+                            <field name="name"/>
+                            <field name="label"/>
+                        </group>
+                        <group>
+                            <field name="licenses"/>
+                            <field name="expiry_date"/>
+                        </group>
+                        <group>
+                            <field name="payment_currency"/>
+                            <field name="payment_price"/>
+                        </group>
+                    </group>
+                    <notebook>
+                        <page string="Roles" name="roles">
+                            <field name="role_ids">
+                                <list editable="bottom">
+                                    <field name="name"/>
+                                    <field name="permission_ids" widget="many2many_tags"/>
+                                </list>
+                            </field>
+                        </page>
+                        <page string="Members" name="members">
+                            <field name="user_rel_ids">
+                                <list editable="bottom">
+                                    <field name="user_id"/>
+                                    <field name="role_id"/>
+                                </list>
+                            </field>
+                        </page>
+                    </notebook>
+                </sheet>
+                <chatter/>
+            </form>
+        </field>
+    </record>
+
+    <record id="action_encoach_entity" model="ir.actions.act_window">
+        <field name="name">Entities</field>
+        <field name="res_model">encoach.entity</field>
+        <field name="view_mode">list,form</field>
+        <field name="help" type="html">
+            <p class="o_view_nocontent_smiling_face">
+                Create your first entity (organization).
+            </p>
+            <p>
+                Entities represent organizations such as schools or companies.
+                Each entity has licenses, members, and roles.
+            </p>
+        </field>
+    </record>
+
+    <menuitem id="menu_encoach_entity"
+        name="Entities"
+        parent="encoach_core.menu_encoach_users"
+        action="action_encoach_entity"
+        sequence="10"/>
+</odoo>

encoach_core/views/invite_views.xml

@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <record id="view_encoach_invite_tree" model="ir.ui.view">
+        <field name="name">encoach.invite.tree</field>
+        <field name="model">encoach.invite</field>
+        <field name="arch" type="xml">
+            <list string="Invites" editable="bottom">
+                <field name="from_user_id"/>
+                <field name="to_user_id"/>
+                <field name="entity_id"/>
+                <field name="status"/>
+            </list>
+        </field>
+    </record>
+
+    <record id="view_encoach_invite_form" model="ir.ui.view">
+        <field name="name">encoach.invite.form</field>
+        <field name="model">encoach.invite</field>
+        <field name="arch" type="xml">
+            <form string="Invite">
+                <header>
+                    <button name="action_accept" string="Accept" type="object"
+                        class="btn-primary" invisible="status != 'pending'"/>
+                    <button name="action_decline" string="Decline" type="object"
+                        invisible="status != 'pending'"/>
+                </header>
+                <sheet>
+                    <group>
+                        <field name="from_user_id"/>
+                        <field name="to_user_id"/>
+                        <field name="entity_id"/>
+                        <field name="status"/>
+                    </group>
+                </sheet>
+            </form>
+        </field>
+    </record>
+
+    <record id="action_encoach_invite" model="ir.actions.act_window">
+        <field name="name">Invites</field>
+        <field name="res_model">encoach.invite</field>
+        <field name="view_mode">list,form</field>
+        <field name="help" type="html">
+            <p class="o_view_nocontent_smiling_face">
+                No invites yet.
+            </p>
+            <p>
+                Invites allow users to join entities.
+                Pending invites can be accepted or declined.
+            </p>
+        </field>
+    </record>
+
+    <menuitem id="menu_encoach_invite"
+        name="Invites"
+        parent="encoach_core.menu_encoach_users"
+        action="action_encoach_invite"
+        sequence="30"/>
+</odoo>

encoach_core/views/menu.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <menuitem id="menu_encoach_root" name="EnCoach" sequence="100"/>
+
+    <menuitem id="menu_encoach_users" name="Users &amp; Entities" parent="menu_encoach_root" sequence="10"/>
+    <menuitem id="menu_encoach_exams" name="Exams" parent="menu_encoach_root" sequence="20"/>
+    <menuitem id="menu_encoach_classroom" name="Classroom" parent="menu_encoach_root" sequence="30"/>
+    <menuitem id="menu_encoach_ai" name="AI &amp; Grading" parent="menu_encoach_root" sequence="40"/>
+    <menuitem id="menu_encoach_training" name="Training" parent="menu_encoach_root" sequence="50"/>
+    <menuitem id="menu_encoach_subscription" name="Subscriptions" parent="menu_encoach_root" sequence="60"/>
+    <menuitem id="menu_encoach_support" name="Support" parent="menu_encoach_root" sequence="70"/>
+    <menuitem id="menu_encoach_config" name="Configuration" parent="menu_encoach_root" sequence="90"/>
+</odoo>

encoach_core/views/permission_views.xml

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <record id="view_encoach_permission_tree" model="ir.ui.view">
+        <field name="name">encoach.permission.tree</field>
+        <field name="model">encoach.permission</field>
+        <field name="arch" type="xml">
+            <list string="Permissions" editable="bottom">
+                <field name="topic"/>
+                <field name="perm_type"/>
+            </list>
+        </field>
+    </record>
+
+    <record id="view_encoach_permission_form" model="ir.ui.view">
+        <field name="name">encoach.permission.form</field>
+        <field name="model">encoach.permission</field>
+        <field name="arch" type="xml">
+            <form string="Permission">
+                <sheet>
+                    <group>
+                        <field name="topic"/>
+                        <field name="perm_type"/>
+                    </group>
+                </sheet>
+            </form>
+        </field>
+    </record>
+
+    <record id="action_encoach_permission" model="ir.actions.act_window">
+        <field name="name">Permissions</field>
+        <field name="res_model">encoach.permission</field>
+        <field name="view_mode">list,form</field>
+        <field name="help" type="html">
+            <p class="o_view_nocontent_smiling_face">
+                Create your first permission.
+            </p>
+            <p>
+                Permissions define what actions can be performed on each topic.
+                Assign permissions to roles.
+            </p>
+        </field>
+    </record>
+
+    <menuitem id="menu_encoach_permission"
+        name="Permissions"
+        parent="encoach_core.menu_encoach_config"
+        action="action_encoach_permission"
+        sequence="20"/>
+</odoo>

encoach_core/views/res_users_views.xml

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <record id="view_res_users_form_encoach" model="ir.ui.view">
+        <field name="name">res.users.form.encoach</field>
+        <field name="model">res.users</field>
+        <field name="inherit_id" ref="base.view_users_form"/>
+        <field name="arch" type="xml">
+            <xpath expr="//notebook" position="inside">
+                <page string="EnCoach" name="encoach">
+                    <group>
+                        <group>
+                            <field name="encoach_type"/>
+                            <field name="focus"/>
+                            <field name="levels" widget="json"/>
+                            <field name="desired_levels" widget="json"/>
+                            <field name="is_verified"/>
+                            <field name="subscription_expiration"/>
+                            <field name="registration_date"/>
+                        </group>
+                        <group>
+                            <field name="bio"/>
+                            <field name="profile_picture"/>
+                            <field name="encoach_status"/>
+                            <field name="is_first_login"/>
+                            <field name="last_login"/>
+                            <field name="legacy_id"/>
+                        </group>
+                    </group>
+                    <field name="entity_rel_ids">
+                        <list editable="bottom">
+                            <field name="entity_id"/>
+                            <field name="role_id"/>
+                        </list>
+                    </field>
+                </page>
+            </xpath>
+        </field>
+    </record>
+</odoo>

encoach_core/views/role_views.xml

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <record id="view_encoach_role_tree" model="ir.ui.view">
+        <field name="name">encoach.role.tree</field>
+        <field name="model">encoach.role</field>
+        <field name="arch" type="xml">
+            <list string="Roles" editable="bottom">
+                <field name="name"/>
+                <field name="entity_id"/>
+            </list>
+        </field>
+    </record>
+
+    <record id="view_encoach_role_form" model="ir.ui.view">
+        <field name="name">encoach.role.form</field>
+        <field name="model">encoach.role</field>
+        <field name="arch" type="xml">
+            <form string="Role">
+                <sheet>
+                    <group>
+                        <field name="name"/>
+                        <field name="entity_id"/>
+                        <field name="permission_ids" widget="many2many_checkboxes"/>
+                    </group>
+                </sheet>
+            </form>
+        </field>
+    </record>
+
+    <record id="action_encoach_role" model="ir.actions.act_window">
+        <field name="name">Roles</field>
+        <field name="res_model">encoach.role</field>
+        <field name="view_mode">list,form</field>
+        <field name="help" type="html">
+            <p class="o_view_nocontent_smiling_face">
+                Create your first role.
+            </p>
+            <p>
+                Roles define permissions within an entity.
+                Assign permissions to roles to control what users can do.
+            </p>
+        </field>
+    </record>
+
+    <menuitem id="menu_encoach_role"
+        name="Roles"
+        parent="encoach_core.menu_encoach_config"
+        action="action_encoach_role"
+        sequence="10"/>
+</odoo>

encoach_core/views/user_entity_rel_views.xml

@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<odoo>
+    <record id="view_encoach_user_entity_rel_tree" model="ir.ui.view">
+        <field name="name">encoach.user.entity.rel.tree</field>
+        <field name="model">encoach.user.entity.rel</field>
+        <field name="arch" type="xml">
+            <list string="User-Entity Memberships" editable="bottom">
+                <field name="user_id"/>
+                <field name="entity_id"/>
+                <field name="role_id"/>
+            </list>
+        </field>
+    </record>
+
+    <record id="view_encoach_user_entity_rel_form" model="ir.ui.view">
+        <field name="name">encoach.user.entity.rel.form</field>
+        <field name="model">encoach.user.entity.rel</field>
+        <field name="arch" type="xml">
+            <form string="User-Entity Membership">
+                <sheet>
+                    <group>
+                        <field name="user_id"/>
+                        <field name="entity_id"/>
+                        <field name="role_id"/>
+                    </group>
+                </sheet>
+            </form>
+        </field>
+    </record>
+
+    <record id="action_encoach_user_entity_rel" model="ir.actions.act_window">
+        <field name="name">User-Entity Memberships</field>
+        <field name="res_model">encoach.user.entity.rel</field>
+        <field name="view_mode">list,form</field>
+        <field name="help" type="html">
+            <p class="o_view_nocontent_smiling_face">
+                No memberships yet.
+            </p>
+            <p>
+                User-entity memberships link users to entities with optional roles.
+            </p>
+        </field>
+    </record>
+
+    <menuitem id="menu_encoach_user_entity_rel"
+        name="Memberships"
+        parent="encoach_core.menu_encoach_users"
+        action="action_encoach_user_entity_rel"
+        sequence="40"/>
+</odoo>