Deploy GapGuide backend (Docker)

.dockerignore

@@ -0,0 +1,11 @@
+venv/
+**/__pycache__/
+*.pyc
+.pytest_cache/
+logs/
+*.log
+seed_data/onet_dump/
+**/tests/
+.git/
+.env
+staticfiles/

.env.example

@@ -0,0 +1,33 @@
+SECRET_KEY=your-super-secret-key-change-in-production
+DEBUG=True
+DB_NAME=gapguide_db
+DB_USER=postgres
+DB_PASSWORD=postgres
+DB_HOST=localhost
+DB_PORT=5432
+ALLOWED_HOSTS=localhost,127.0.0.1
+CORS_ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
+
+# Optional. Enables the "Import modules from URL" admin action to read chapter
+# markers from single YouTube videos via the Data API v3 (free, 10k units/day).
+# Leave unset and YouTube imports fall back to manual checkpoint entry.
+# YOUTUBE_API_KEY=
+
+# Prevent __pycache__/*.pyc files from shadowing edited source during dev.
+PYTHONDONTWRITEBYTECODE=1
+
+# ---------------------------------------------------------------------------
+# Production / deployment only (Hugging Face Space secrets). Leave ALL of these
+# UNSET locally — when unset the app uses the local DB_* + DEBUG=True defaults
+# above. Do NOT put these in a local .env.
+# ---------------------------------------------------------------------------
+# DEBUG=False
+# SECRET_KEY=<a long random secret>
+# ALLOWED_HOSTS=*
+# DATABASE_URL=postgresql://USER:PASSWORD@HOST/DB?sslmode=require   # Neon DIRECT (non-pooled) URL
+# CORS_ALLOWED_ORIGINS=https://<your-project>.vercel.app
+# CSRF_TRUSTED_ORIGINS=https://<your-space>.hf.space
+# SECURE_SSL_REDIRECT=False        # HF terminates HTTPS at its edge
+# DEMO_ADMIN_PASSWORD=<private admin password for the public deploy>
+# BUILD_EMBEDDINGS=1               # first boot only: build SBERT skill embeddings
+# THROTTLE_RESUME=200/hour         # optional: raise the resume-parse rate for a demo

.gitattributes

@@ -1,35 +1 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.sh text eol=lf

.ruff_cache/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by ruff.
+*

.ruff_cache/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

Dockerfile

@@ -0,0 +1,43 @@
+# GapGuide backend — Hugging Face Docker Space image.
+# Django + DRF API with the in-process NER chain, served by gunicorn on :7860.
+FROM python:3.13-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    HF_HOME=/app/.cache/huggingface \
+    NLTK_DATA=/app/.cache/nltk
+
+# HF Spaces run the container as UID 1000.
+RUN useradd -m -u 1000 appuser
+WORKDIR /app
+
+# Python deps first for better layer caching. requirements.txt carries the
+# torch CPU --extra-index-url, so CPU wheels resolve here (verified: torch
+# 2.11/2.12 +cpu cp313 manylinux exist).
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt \
+    && python -m spacy download en_core_web_sm
+
+# App code, owned by the runtime user in a single COPY (no recursive-chown bloat).
+COPY --chown=1000:1000 . .
+
+# Make the dirs the next steps write to owned by UID 1000 (the /app dir itself
+# is root-owned from WORKDIR; chown only the specific dirs, not the whole tree).
+RUN mkdir -p /app/.cache/huggingface /app/.cache/nltk /app/staticfiles \
+    && chown 1000:1000 /app /app/.cache /app/.cache/huggingface /app/.cache/nltk /app/staticfiles
+
+USER 1000
+
+# Bake everything the NER chain downloads → fast, offline-safe first parse in prod.
+# Runs as UID 1000 so caches land under the owned /app/.cache.
+RUN python -m nltk.downloader -d /app/.cache/nltk stopwords punkt punkt_tab \
+    && python scripts/prefetch_models.py
+
+# Collect Django admin / DRF static for WhiteNoise. Inline build env sidesteps the
+# DEBUG=False "insecure SECRET_KEY" guard; it does not persist to runtime.
+RUN DEBUG=True SECRET_KEY=build-only python manage.py collectstatic --noinput
+
+EXPOSE 7860
+# /bin/sh form survives a Windows upload (no exec-bit / shebang dependency).
+ENTRYPOINT ["/bin/sh", "entrypoint.sh"]

INSTALL.md

@@ -0,0 +1,118 @@
+# Local Setup — GapGuide Backend
+
+Prerequisites: Windows 10/11, PostgreSQL 17 installed, Python 3.13 (already set up at `backend/venv/`), Node 20+ for the frontend.
+
+## 1. Install pgvector extension on PostgreSQL 17
+
+Module 8 Layer 4 uses `pgvector` for SBERT cosine similarity. `CREATE EXTENSION vector` fails until the extension files are installed into the PostgreSQL server directory. Two options:
+
+### Option A — Precompiled binary (recommended, ~2 minutes)
+
+1. Go to https://github.com/andreiramani/pgvector_pgsql_windows/releases
+2. Download the release tagged `0.8.2_17.6` (built against PostgreSQL 17.6; works on 17.3+ — older 17.0–17.2 hit a linker bug).
+3. Extract. You should see `vector.control`, `vector--*.sql`, and `vector.dll`.
+4. Copy files:
+   - `vector.control` and `vector--*.sql` → `C:\Program Files\PostgreSQL\17\share\extension\`
+   - `vector.dll` → `C:\Program Files\PostgreSQL\17\lib\`
+   - Administrator rights required (Program Files is protected).
+5. Verify in psql:
+   ```
+   psql -U postgres -d gapguide -c "CREATE EXTENSION IF NOT EXISTS vector; SELECT '[1,2,3]'::vector;"
+   ```
+   Output should include `[1,2,3]`.
+
+### Option B — Build from source (~30 min, no trusted binary)
+
+1. Install Visual Studio with "Desktop development with C++".
+2. Open "x64 Native Tools Command Prompt for VS" as **administrator**.
+3. Run:
+   ```
+   set "PGROOT=C:\Program Files\PostgreSQL\17"
+   cd %TEMP%
+   git clone --branch v0.8.2 https://github.com/pgvector/pgvector.git
+   cd pgvector
+   nmake /F Makefile.win
+   nmake /F Makefile.win install
+   ```
+4. Verify as in Option A step 5.
+
+## 2. Python dependencies
+
+```powershell
+cd backend
+.\venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+python -m spacy download en_core_web_sm
+```
+
+First install is ~5 minutes (torch CPU wheel is the heaviest at ~200 MB).
+
+The NER layers will use `en_core_web_sm` (12 MB) by default. If you want
+slightly better noun-phrase quality on paraphrased CVs, upgrade to
+`en_core_web_lg` (~560 MB) — the layers auto-detect and prefer `_lg`:
+
+```powershell
+python -m spacy download en_core_web_lg
+```
+
+HuggingFace models download lazily on first parse into `%USERPROFILE%\.cache\huggingface` (~1 GB total across Nucha BERT, JobBERT, SBERT). Subsequent parses are instant.
+
+## 3. Database setup
+
+```powershell
+# create the DB (if fresh)
+createdb -U postgres gapguide
+
+# migrate (requires pgvector from step 1)
+python manage.py migrate
+
+# seed the catalog + 5 demo users
+python manage.py seed_initial_skills
+python manage.py seed_initial_roles
+python manage.py seed_initial_resources
+python manage.py seed_demo_users
+
+# build SBERT embeddings for the Skill catalog (Module 8 Layer 4)
+python scripts/build_skill_embeddings.py
+```
+
+Demo user login: `demo.partial@gapguide.test` / `DemoPass123!`.
+
+## 4. Run locally
+
+```powershell
+# terminal 1 — backend
+cd backend
+.\venv\Scripts\Activate.ps1
+python manage.py runserver
+
+# terminal 2 — frontend
+cd frontend
+npm install
+npm run dev
+```
+
+Open http://localhost:8080.
+
+## 5. Running tests
+
+```powershell
+cd backend
+
+# CI baseline (no ML, seconds)
+$env:GAPGUIDE_PARSE_LAYERS = "lexical"
+pytest -q
+
+# ML smoke test (downloads models on first run — ~15 min first time)
+Remove-Item Env:\GAPGUIDE_PARSE_LAYERS
+$env:GAPGUIDE_ML_SMOKE = "1"
+pytest apps/accounts/tests/test_resume_parser_integration.py -q
+```
+
+## Troubleshooting
+
+- **`extension "vector" is not available`** — pgvector not installed on your Postgres. Redo step 1. The `vector.control` file must exist in PostgreSQL's `share\extension\` directory.
+- **`ModuleNotFoundError: pgvector`** — `pip install -r requirements.txt` hasn't run (or ran in a different venv). Activate the venv first.
+- **`spaCy model not found`** — run `python -m spacy download en_core_web_lg`.
+- **Slow first resume parse** — normal. The NER chain downloads ~1 GB of models on first call. Subsequent parses use the cache.
+- **`GAPGUIDE_PARSE_LAYERS=lexical`** — lets you run the backend without any ML deps loaded. Useful during dev when you don't want the first-call model downloads.

README.md

@@ -1,10 +1,18 @@
 ---
-title: Gapguide Api
-emoji: 👀
-colorFrom: red
-colorTo: yellow
+title: GapGuide API
+emoji: 🎯
+colorFrom: blue
+colorTo: indigo
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# GapGuide API
+
+Django + DRF backend for **GapGuide** (AI Job Fit & Skill Gap Assistant), with the
+in-process resume-parsing NER chain. Deployed as a Hugging Face Docker Space; the
+React frontend is hosted separately on Vercel and talks to this API under `/api`.
+
+The container runs database migrations and idempotent catalog/demo seeds on start,
+then serves the API with gunicorn on port 7860. See the repository for full docs.

apps/accounts/admin.py

@@ -0,0 +1,26 @@
+from django.contrib import admin
+from django.contrib.auth.admin import UserAdmin as BaseUserAdmin
+from .models import User
+
+
+@admin.register(User)
+class UserAdmin(BaseUserAdmin):
+    list_display = ['email', 'name', 'role_type', 'is_active', 'created_at']
+    list_filter = ['role_type', 'is_active', 'is_staff']
+    search_fields = ['email', 'name']
+    ordering = ['-created_at']
+    readonly_fields = ['created_at']
+
+    fieldsets = (
+        (None, {'fields': ('email', 'password')}),
+        ('Personal info', {'fields': ('name', 'role_type')}),
+        ('Permissions', {'fields': ('is_active', 'is_staff', 'is_superuser', 'groups', 'user_permissions')}),
+        ('Important dates', {'fields': ('last_login', 'created_at')}),
+    )
+
+    add_fieldsets = (
+        (None, {
+            'classes': ('wide',),
+            'fields': ('email', 'password1', 'password2', 'name', 'role_type'),
+        }),
+    )

apps/accounts/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class AccountsConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'apps.accounts'

apps/accounts/management/commands/seed_demo_users.py

@@ -0,0 +1,290 @@
+"""Seed 5 demo users spanning the WEAK, PARTIAL, and STRONG readiness bands plus the closed loop.
+
+Idempotent: re-running the command does not duplicate users or create
+stacked UserProgress rows. Designed for local demo + manual QA.
+
+Personas:
+  1. demo.weak       — Data Scientist, Python=30 only.       WEAK band.
+  2. demo.partial    — Data Scientist, Python=80 SQL=90 Scikit-learn=0. PARTIAL + cap.
+  3. demo.ready      — Frontend Developer, skills ≥ INTERMEDIATE. STRONG band.
+  4. demo.closedloop — ML Engineer, one COMPLETED resource → upgrade pending.
+  5. demo.admin      — superuser, for Module 7 RoleAdmin demos.
+
+Password for every persona: DemoPass123! (printed in command output).
+"""
+from __future__ import annotations
+
+import os
+
+from django.contrib.auth import get_user_model
+from django.core.management.base import BaseCommand
+from django.db import transaction
+from django.utils import timezone
+
+from apps.accounts.models import UserProfile
+from apps.progress.models import UserProgress
+from apps.resources.models import Resource, SkillResource
+from apps.roles.models import Role, UserTargetRole
+from apps.skills.models import Skill, UserSkill
+from apps.skills.utils import proficiency_to_level
+
+
+DEMO_PASSWORD = 'DemoPass123!'
+# On a public deployment the superuser must NOT carry the well-known demo
+# password. Override the admin password via the DEMO_ADMIN_PASSWORD env var;
+# falls back to DEMO_PASSWORD locally where the env var is unset.
+ADMIN_PASSWORD = os.environ.get('DEMO_ADMIN_PASSWORD', DEMO_PASSWORD)
+
+
+# (email, name, target_role_name, {skill_name: proficiency}, degree, semester)
+# target_role_name=None skips target setup (only persona 5/admin).
+PERSONAS: list[dict] = [
+    {
+        'email': 'demo.weak@gapguide.test',
+        'name': 'Demo Weak',
+        'target': 'Data Scientist',
+        'skills': {'Python': 30},
+        'degree': 'BSDS',
+        'semester': 4,
+    },
+    {
+        'email': 'demo.partial@gapguide.test',
+        'name': 'Demo Partial',
+        'target': 'Data Scientist',
+        # Most Data Scientist skills at MET levels so raw readiness lands
+        # well above the 60 mandatory-cap. The single MISSING mandatory
+        # skill (Scikit-learn) is what pulls the score down to the cap —
+        # exercising the "Partial Match" band + mandatory_cap_applied path.
+        # Strong coverage across the Data Scientist skill set with ONE
+        # mandatory miss (Scikit-learn=0). Raw readiness lands comfortably
+        # above the 60 cap so the mandatory-cap logic actually fires and
+        # mandatory_cap_applied=True becomes visible in the demo.
+        'skills': {
+            'Python': 80,
+            'SQL': 90,
+            'Pandas': 75,
+            'NumPy': 75,
+            'PyTorch': 70,
+            'Statistical Hypothesis Testing': 70,
+            'Git': 85,
+            'Scikit-learn': 0,     # MISSING + mandatory -> triggers cap
+            'Apache Spark': 60,
+            'AWS': 60,
+            'Docker': 55,
+            'Feature Engineering': 70,
+            'Matplotlib': 70,
+            'Microsoft Power BI': 50,
+            'Tableau': 65,
+            'TensorFlow': 55,
+        },
+        'degree': 'BSDS',
+        'semester': 6,
+    },
+    {
+        'email': 'demo.ready@gapguide.test',
+        'name': 'Demo Ready',
+        'target': 'Frontend Developer',
+        # Filled in dynamically below from Frontend Developer's RoleSkills.
+        'skills': None,
+        'degree': 'BSCS',
+        'semester': 7,
+    },
+    {
+        'email': 'demo.closedloop@gapguide.test',
+        'name': 'Demo ClosedLoop',
+        'target': 'Machine Learning Engineer',
+        # Mid-stage ML learner: most core skills MET, a few shortfalls, and
+        # Python sits at 60 so the COMPLETED Python resource triggers a
+        # "bump 60 -> 85" upgrade suggestion on the Progress page.
+        'skills': {
+            'Python': 60,
+            'SQL': 70,
+            'NumPy': 65,
+            'Pandas': 60,
+            'Scikit-learn': 55,
+            'PyTorch': 50,
+            'TensorFlow': 45,
+            'Git': 75,
+            'GitHub': 70,
+            'Docker': 50,
+            'AWS': 40,
+        },
+        'degree': 'BSDS',
+        'semester': 8,
+    },
+    {
+        'email': 'demo.admin@gapguide.test',
+        'name': 'Demo Admin',
+        'target': None,
+        'skills': {},
+        'is_staff': True,
+        'is_superuser': True,
+        'role_type': 'ADMIN',
+    },
+]
+
+
+class Command(BaseCommand):
+    help = (
+        "Create or refresh 5 demo users (weak / partial / ready / closedloop / "
+        "admin) spanning the WEAK/PARTIAL/STRONG readiness bands and the "
+        "skill-upgrade loop. Idempotent; re-run after seed catalog changes."
+    )
+
+    def handle(self, *args, **options):
+        User = get_user_model()
+
+        created_count = 0
+        updated_count = 0
+        warnings: list[str] = []
+
+        for spec in PERSONAS:
+            with transaction.atomic():
+                user, created = User.objects.update_or_create(
+                    email=spec['email'],
+                    defaults={
+                        'username': spec['email'],
+                        'name': spec['name'],
+                        'role_type': spec.get('role_type', 'STUDENT'),
+                        'is_staff': spec.get('is_staff', False),
+                        'is_superuser': spec.get('is_superuser', False),
+                    },
+                )
+                pwd = ADMIN_PASSWORD if spec.get('is_superuser') else DEMO_PASSWORD
+                user.set_password(pwd)
+                user.save(update_fields=['password'])
+                if created:
+                    created_count += 1
+                else:
+                    updated_count += 1
+
+                UserProfile.objects.update_or_create(
+                    user=user,
+                    defaults={
+                        'degree': spec.get('degree', ''),
+                        'semester': spec.get('semester'),
+                        'interests': '',
+                        'bio': f"Demo persona: {spec['name']}.",
+                    },
+                )
+
+                target_name = spec.get('target')
+                if target_name:
+                    role = Role.objects.filter(role_name=target_name).first()
+                    if role is None:
+                        warnings.append(
+                            f"{spec['email']}: target role '{target_name}' not in catalog "
+                            f"(did you run seed_initial_roles?). Skipping target set."
+                        )
+                    else:
+                        UserTargetRole.objects.filter(user=user).delete()
+                        UserTargetRole.objects.create(
+                            user=user, role=role, is_active=True,
+                        )
+
+                skills_spec = spec['skills']
+                if skills_spec is None:
+                    # demo.ready persona: build from the target role's required skills
+                    skills_spec = self._ready_persona_skills(target_name, warnings, spec['email'])
+
+                for skill_name, proficiency in (skills_spec or {}).items():
+                    skill = Skill.objects.filter(skill_name=skill_name).first()
+                    if skill is None:
+                        warnings.append(
+                            f"{spec['email']}: skill '{skill_name}' not in catalog. Skipping."
+                        )
+                        continue
+                    UserSkill.objects.update_or_create(
+                        user=user, skill=skill,
+                        defaults={
+                            'proficiency': proficiency,
+                            'user_level': proficiency_to_level(proficiency),
+                            'dismissed_upgrade_at': None,
+                        },
+                    )
+
+                # Persona 4: mark one Python-linked resource COMPLETED so the
+                # upgrade-suggestion engine has a reason to fire.
+                if spec['email'].startswith('demo.closedloop@'):
+                    self._seed_closed_loop_completion(user, warnings)
+
+        # Summary output.
+        self.stdout.write(self.style.SUCCESS(
+            f"Demo users: {created_count} created, {updated_count} refreshed "
+            f"(password for all: {DEMO_PASSWORD})"
+        ))
+        for line in warnings:
+            self.stdout.write(self.style.WARNING('  ! ' + line))
+        self.stdout.write("")
+        for spec in PERSONAS:
+            self.stdout.write(
+                f"  {spec['email']:<40} -> {spec.get('target') or '(admin)'}"
+            )
+
+    @staticmethod
+    def _ready_persona_skills(
+        target_name: str | None, warnings: list, email: str,
+    ) -> dict[str, int]:
+        """demo.ready has every required skill comfortably above its threshold.
+
+        INTERMEDIATE threshold=60, ADVANCED threshold=100. We set proficiency
+        80 for INTERMEDIATE skills (well above threshold → fully satisfied) and
+        100 for ADVANCED skills, so every skill is MET → readiness 100 (STRONG).
+        This persona has no completed resource, so no upgrade suggestion fires.
+        """
+        if not target_name:
+            return {}
+        role = Role.objects.filter(role_name=target_name).first()
+        if role is None:
+            warnings.append(
+                f"{email}: cannot populate skills — target role '{target_name}' missing."
+            )
+            return {}
+        skills: dict[str, int] = {}
+        for rs in role.role_skills.select_related('skill'):
+            if rs.required_level == 'ADVANCED':
+                skills[rs.skill.skill_name] = 100
+            elif rs.required_level == 'INTERMEDIATE':
+                skills[rs.skill.skill_name] = 80
+            else:  # BEGINNER
+                skills[rs.skill.skill_name] = 55
+        return skills
+
+    @staticmethod
+    def _seed_closed_loop_completion(user, warnings: list) -> None:
+        """Mark one Python-linked Resource as COMPLETED for the closedloop user.
+
+        Given Python=60 on the user, the upgrade engine will suggest 85 when
+        it sees a completed Python resource. This makes the "Upgrade pending"
+        Alert card (Progress.jsx:146) appear in the demo without any clicks.
+        """
+        python = Skill.objects.filter(skill_name='Python').first()
+        if python is None:
+            warnings.append(
+                "closedloop: Python skill missing from catalog — skipping closed-loop seed."
+            )
+            return
+
+        resource = (
+            Resource.objects
+            .filter(skills=python)
+            .order_by('id')
+            .first()
+        )
+        if resource is None:
+            warnings.append(
+                "closedloop: no Resource links to Python — skipping closed-loop seed "
+                "(did you run seed_initial_resources?)."
+            )
+            return
+
+        now = timezone.now()
+        UserProgress.objects.update_or_create(
+            user=user, resource=resource,
+            defaults={
+                'status': 'COMPLETED',
+                'progress': 100,
+                'started_at': now,
+                'completed_at': now,
+            },
+        )

apps/accounts/migrations/0001_initial.py

@@ -0,0 +1,46 @@
+# Generated by Django 6.0.4 on 2026-04-07 18:50
+
+import django.contrib.auth.models
+import django.contrib.auth.validators
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('auth', '0012_alter_user_first_name_max_length'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='User',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('password', models.CharField(max_length=128, verbose_name='password')),
+                ('last_login', models.DateTimeField(blank=True, null=True, verbose_name='last login')),
+                ('is_superuser', models.BooleanField(default=False, help_text='Designates that this user has all permissions without explicitly assigning them.', verbose_name='superuser status')),
+                ('username', models.CharField(error_messages={'unique': 'A user with that username already exists.'}, help_text='Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.', max_length=150, unique=True, validators=[django.contrib.auth.validators.UnicodeUsernameValidator()], verbose_name='username')),
+                ('first_name', models.CharField(blank=True, max_length=150, verbose_name='first name')),
+                ('last_name', models.CharField(blank=True, max_length=150, verbose_name='last name')),
+                ('is_staff', models.BooleanField(default=False, help_text='Designates whether the user can log into this admin site.', verbose_name='staff status')),
+                ('is_active', models.BooleanField(default=True, help_text='Designates whether this user should be treated as active. Unselect this instead of deleting accounts.', verbose_name='active')),
+                ('date_joined', models.DateTimeField(default=django.utils.timezone.now, verbose_name='date joined')),
+                ('name', models.CharField(blank=True, max_length=255)),
+                ('email', models.EmailField(max_length=254, unique=True)),
+                ('role_type', models.CharField(choices=[('STUDENT', 'Student'), ('ADMIN', 'Admin')], default='STUDENT', max_length=10)),
+                ('groups', models.ManyToManyField(blank=True, help_text='The groups this user belongs to. A user will get all permissions granted to each of their groups.', related_name='user_set', related_query_name='user', to='auth.group', verbose_name='groups')),
+                ('user_permissions', models.ManyToManyField(blank=True, help_text='Specific permissions for this user.', related_name='user_set', related_query_name='user', to='auth.permission', verbose_name='user permissions')),
+            ],
+            options={
+                'verbose_name': 'user',
+                'verbose_name_plural': 'users',
+                'abstract': False,
+            },
+            managers=[
+                ('objects', django.contrib.auth.models.UserManager()),
+            ],
+        ),
+    ]

apps/accounts/migrations/0002_user_created_at_alter_user_role_type.py

@@ -0,0 +1,25 @@
+# Generated by Django 6.0.4 on 2026-04-07 19:28
+
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('accounts', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='user',
+            name='created_at',
+            field=models.DateTimeField(auto_now_add=True, default=django.utils.timezone.now),
+            preserve_default=False,
+        ),
+        migrations.AlterField(
+            model_name='user',
+            name='role_type',
+            field=models.CharField(choices=[('STUDENT', 'Student'), ('ADMIN', 'Admin')], default='STUDENT', max_length=20),
+        ),
+    ]

apps/accounts/migrations/0003_userprofile.py

@@ -0,0 +1,28 @@
+# Generated by Django 6.0.4 on 2026-04-07 19:34
+
+import django.core.validators
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('accounts', '0002_user_created_at_alter_user_role_type'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='UserProfile',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('degree', models.CharField(blank=True, max_length=255)),
+                ('semester', models.IntegerField(blank=True, null=True, validators=[django.core.validators.MinValueValidator(1), django.core.validators.MaxValueValidator(12)])),
+                ('interests', models.TextField(blank=True)),
+                ('bio', models.TextField(blank=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('user', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, related_name='profile', to=settings.AUTH_USER_MODEL)),
+            ],
+        ),
+    ]

apps/accounts/models.py

@@ -0,0 +1,41 @@
+from django.conf import settings
+from django.contrib.auth.models import AbstractUser
+from django.core.validators import MinValueValidator, MaxValueValidator
+from django.db import models
+
+
+class User(AbstractUser):
+    ROLE_CHOICES = [
+        ('STUDENT', 'Student'),
+        ('ADMIN', 'Admin'),
+    ]
+
+    name = models.CharField(max_length=255, blank=True)
+    email = models.EmailField(unique=True)
+    role_type = models.CharField(max_length=20, choices=ROLE_CHOICES, default='STUDENT')
+    created_at = models.DateTimeField(auto_now_add=True)
+
+    USERNAME_FIELD = 'email'
+    REQUIRED_FIELDS = ['username', 'name']
+
+    def __str__(self):
+        return self.email
+
+
+class UserProfile(models.Model):
+    user = models.OneToOneField(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name='profile'
+    )
+    degree = models.CharField(max_length=255, blank=True)
+    semester = models.IntegerField(
+        null=True, blank=True,
+        validators=[MinValueValidator(1), MaxValueValidator(12)]
+    )
+    interests = models.TextField(blank=True)
+    bio = models.TextField(blank=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    def __str__(self):
+        return f'Profile of {self.user.email}'

apps/accounts/ner/__init__.py

@@ -0,0 +1,57 @@
+"""NER layer package for Module 8 resume parsing.
+
+Layers (merge-all semantics — see research/06-dataset-sourcing.md §5 and
+the plan at ~/.claude/plans/okay-plan-for-7a-fluffy-marshmallow.md):
+
+  1. nucha   — Nucha/Nucha_ITSkillNER_BERT (MIT, F1 0.90)
+  2. jobbert — jjzha/jobbert_skill_extraction (license unspecified, FYP-OK)
+  3. skillner — rule-based, EMSI taxonomy (Nov 2021 release, still works)
+  4. sbert   — SentenceTransformer('all-MiniLM-L6-v2') + pgvector cosine
+
+Each concrete layer implements ``NerLayer`` and exposes a module-level
+lazy singleton so the HF models only load on first call. The dispatcher in
+``resume_parser._predict_skills_from_text`` invokes the layers in order,
+catches any import / timeout / model-download error per layer, and unions
+the results into one {alias: max_confidence} dict.
+
+The lexical floor (``ner.lexical``) is always run last even if the higher
+layers succeed — it guarantees the endpoint returns at least the catalog
+matches regardless of ML-layer availability.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class NerLayer(ABC):
+    """Contract every NER layer must satisfy.
+
+    Implementations should:
+      * Keep the model as a module-level singleton, loaded on first call.
+      * Catch *internal* model errors and return an empty dict rather than
+        raising — the dispatcher already wraps calls in try/except, but
+        returning {} for recoverable failures keeps the log quieter.
+      * Never raise for an empty or non-English input — just return {}.
+    """
+
+    #: Short stable identifier used in the response's ``parser_version`` list.
+    #: Keep lowercase, no spaces.
+    name: str = "abstract"
+
+    @abstractmethod
+    def predict(self, text: str) -> dict[str, float]:
+        """Return {skill_or_alias_name: confidence_0_to_1}.
+
+        Keys are free-text — the dispatcher runs alias resolution against the
+        Skill catalog before they reach the user. Values are [0, 1] floats.
+        """
+        raise NotImplementedError
+
+    def available(self) -> bool:
+        """Cheap check the dispatcher calls before invoking predict().
+
+        Default: attempt a lazy-import of the layer's heavy deps. Override
+        for layers whose availability depends on external state (e.g. a
+        model being cached locally).
+        """
+        return True

apps/accounts/ner/jobbert.py

@@ -0,0 +1,117 @@
+"""Layer 2: jjzha/jobbert_skill_extraction — SkillSpan-trained BERT NER.
+
+Model: https://huggingface.co/jjzha/jobbert_skill_extraction
+  - 107.7M params, BERT, token-classification, B-Skill/I-Skill labels
+  - License is NOT stated on the model card — OK for academic FYP use only.
+    See research/06-dataset-sourcing.md §5.
+  - Downloads ~440 MB on first use.
+"""
+from __future__ import annotations
+
+import logging
+
+from . import NerLayer
+
+
+logger = logging.getLogger(__name__)
+
+_MODEL_ID = "jjzha/jobbert_skill_extraction"
+_pipeline = None
+_warned_license = False
+
+
+def _get_pipeline():
+    global _pipeline, _warned_license
+    if _pipeline is None:
+        from transformers import pipeline
+        if not _warned_license:
+            logger.info(
+                "jobbert: %s has no stated license; use restricted to "
+                "academic/FYP scope.", _MODEL_ID,
+            )
+            _warned_license = True
+        logger.info("jobbert: loading %s pipeline (first call may be slow)", _MODEL_ID)
+        # Do NOT pass truncation/max_length to the token-classification
+        # pipeline() constructor — its `_sanitize_parameters` rejects them with
+        # a TypeError, which made this whole layer fail to construct and get
+        # silently skipped by the dispatcher. HF auto-truncates in preprocess,
+        # and predict() already slices the input to 4000 chars.
+        _pipeline = pipeline(
+            task="ner",
+            model=_MODEL_ID,
+            aggregation_strategy="simple",
+        )
+    return _pipeline
+
+
+class JobBertLayer(NerLayer):
+    name = "jobbert"
+
+    def predict(self, text: str) -> dict[str, float]:
+        if not text.strip():
+            return {}
+        pipe = _get_pipeline()
+        src = text[:4000]
+        spans = pipe(src)
+
+        out: dict[str, float] = {}
+
+        def _emit(term: str, conf: float) -> None:
+            term = term.strip(" ,.;:-")
+            if len(term) >= 2 and conf > out.get(term, 0.0):
+                out[term] = conf
+
+        # Accumulator for re-stitching a multi-token skill from its char offsets.
+        cur_start = None
+        cur_end = 0
+        cur_conf = 0.0
+
+        def _flush() -> None:
+            nonlocal cur_start, cur_end, cur_conf
+            if cur_start is not None:
+                _emit(src[cur_start:cur_end], cur_conf)
+                cur_start, cur_end, cur_conf = None, 0, 0.0
+
+        for span in spans:
+            # jjzha/jobbert_skill_extraction has exactly one entity type
+            # (SKILL). Under aggregation_strategy="simple", HuggingFace emits
+            # entity_group as the bare BIO prefix ("B" / "I"), so any non-O span
+            # is a skill span.
+            label = (span.get("entity_group") or span.get("entity") or "").upper()
+            if label in ("", "O"):
+                _flush()
+                continue
+            conf = float(span.get("score") or 0.0)
+            start, end = span.get("start"), span.get("end")
+            if start is None or end is None:
+                # No character offsets (slow tokenizer / unit-test stub) — can't
+                # safely merge, so emit the raw word as a standalone term.
+                _flush()
+                _emit(span.get("word") or "", conf)
+                continue
+            # jjzha's labels carry no entity suffix, so aggregation_strategy=
+            # "simple" can't group a skill's B token with its following I tokens
+            # — multi-word skills ("machine learning") fragment. Re-stitch via
+            # offsets: a "B" begins a new skill; an "I" directly adjacent (<=1
+            # char gap, i.e. a single separator) extends the current one.
+            is_continuation = (
+                label != "B" and cur_start is not None and 0 <= start - cur_end <= 1
+            )
+            if is_continuation:
+                cur_end = max(cur_end, end)
+                cur_conf = min(cur_conf, conf)
+            else:
+                _flush()
+                cur_start, cur_end, cur_conf = start, end, conf
+        _flush()
+        return out
+
+    def available(self) -> bool:
+        try:
+            import transformers  # noqa: F401
+            return True
+        except Exception:
+            return False
+
+
+layer = JobBertLayer()

apps/accounts/ner/lexical.py

@@ -0,0 +1,42 @@
+"""Layer 0/floor: lexical catalog matching.
+
+This wraps the existing pdfplumber-free matching logic from the MVP so the
+dispatcher can treat it uniformly with the other layers. Unlike the four
+ML layers, this one is always safe — it has no heavy deps and only touches
+the DB's Skill catalog.
+
+Kept separate from ``resume_parser`` so the dispatcher can invoke it as
+a layer alongside the others rather than having a special-case code path.
+"""
+from __future__ import annotations
+
+from . import NerLayer
+
+
+class LexicalLayer(NerLayer):
+    name = "lexical"
+
+    def predict(self, text: str) -> dict[str, float]:
+        if not text.strip():
+            return {}
+        # Reuse the existing implementation so behaviour stays identical.
+        from apps.accounts.resume_parser import _candidate_matches
+        from apps.skills.models import Skill
+
+        skills = list(Skill.objects.all().only("id", "skill_name"))
+        hits = _candidate_matches(text, skills)
+        # _candidate_matches returns {skill_id: {confidence, proficiency, matched_span}}
+        # — the dispatcher works with {name: confidence}, so remap.
+        by_id = {s.id: s.skill_name for s in skills}
+        out: dict[str, float] = {}
+        for skill_id, data in hits.items():
+            name = by_id.get(skill_id)
+            if name:
+                out[name] = float(data["confidence"])
+        return out
+
+    def available(self) -> bool:
+        return True
+
+
+layer = LexicalLayer()

apps/accounts/ner/nucha.py

@@ -0,0 +1,76 @@
+"""Layer 1: Nucha/Nucha_ITSkillNER_BERT — BERT NER for IT skills.
+
+Model: https://huggingface.co/Nucha/Nucha_ITSkillNER_BERT
+  - MIT license, 108.9M params, BERT architecture
+  - Labels: HSKILL (hard skill) + SSKILL (soft skill), F1 ~0.90
+  - Downloads ~440 MB into %USERPROFILE%\\.cache\\huggingface on first use.
+
+Contract: returns {skill_span_text: confidence}. The dispatcher's alias
+resolver decides which canonical Skill catalog row that maps to.
+"""
+from __future__ import annotations
+
+import logging
+
+from . import NerLayer
+
+
+logger = logging.getLogger(__name__)
+
+_MODEL_ID = "Nucha/Nucha_ITSkillNER_BERT"
+_pipeline = None  # set on first call, persists for the process lifetime
+
+
+def _get_pipeline():
+    """Lazy singleton — the first call does the ~440 MB download; later
+    calls reuse the cached model. Raises on network failure; the dispatcher
+    catches and moves to the next layer.
+    """
+    global _pipeline
+    if _pipeline is None:
+        from transformers import pipeline  # local import keeps lexical-only CI fast
+        logger.info("nucha: loading %s pipeline (first call may be slow)", _MODEL_ID)
+        _pipeline = pipeline(
+            task="ner",
+            model=_MODEL_ID,
+            aggregation_strategy="simple",
+        )
+    return _pipeline
+
+
+class NuchaLayer(NerLayer):
+    name = "nucha"
+
+    def predict(self, text: str) -> dict[str, float]:
+        if not text.strip():
+            return {}
+        pipe = _get_pipeline()
+        # The pipeline returns a list of span dicts with keys
+        # {entity_group, score, word, start, end}. aggregation_strategy="simple"
+        # merges adjacent B-/I- tokens into full spans.
+        spans = pipe(text[:4000])  # cap at ~4K chars to bound latency
+        out: dict[str, float] = {}
+        for span in spans:
+            label = span.get("entity_group") or span.get("entity") or ""
+            if not label.upper().endswith("SKILL"):
+                # Tokens labelled 'O' or padding — drop.
+                continue
+            term = (span.get("word") or "").strip(" ,.;:-")
+            if len(term) < 2:
+                continue
+            conf = float(span.get("score") or 0.0)
+            # Merge duplicates — keep the max confidence seen.
+            if conf > out.get(term, 0.0):
+                out[term] = conf
+        return out
+
+    def available(self) -> bool:
+        try:
+            import transformers  # noqa: F401
+            return True
+        except Exception:
+            return False
+
+
+# Module-level singleton for the dispatcher to import cheaply.
+layer = NuchaLayer()

apps/accounts/ner/sbert.py

@@ -0,0 +1,131 @@
+"""Layer 4: SBERT + pgvector cosine — degraded-fallback canonical mapping.
+
+Uses sentence-transformers/all-MiniLM-L6-v2 (Apache 2.0, 22M params, 384 dims)
+to embed candidate noun phrases from the resume text, then queries the
+SkillEmbedding table via pgvector cosine distance to find the nearest
+catalog skill. This is the always-available fallback for when higher BERT
+layers can't load (memory-limited Render tier, offline, etc.) AND for
+paraphrased skill language that lexical + BERT miss.
+
+Threshold: 0.65 similarity (equivalent to cosine_distance <= 0.35). The
+dispatcher's alias resolver uses the canonical ``skill_name`` keyed output
+directly — no further fuzzy-match hop needed.
+"""
+from __future__ import annotations
+
+import logging
+
+from . import NerLayer
+
+
+logger = logging.getLogger(__name__)
+
+_MODEL_ID = "sentence-transformers/all-MiniLM-L6-v2"
+_SIM_THRESHOLD = 0.65
+
+_model = None
+_nlp = None
+
+
+def _get_model():
+    global _model
+    if _model is None:
+        from sentence_transformers import SentenceTransformer
+        logger.info("sbert: loading %s (first call may be slow)", _MODEL_ID)
+        _model = SentenceTransformer(_MODEL_ID)
+    return _model
+
+
+def _get_nlp():
+    """Reuse spaCy's en_core_web_lg for noun-phrase extraction.
+
+    If skillNer already loaded it, great — it's a module-level singleton in
+    that layer too. Otherwise we load our own.
+    """
+    global _nlp
+    if _nlp is None:
+        # Reuse skillner's loaded model if possible to save ~560 MB of RAM.
+        from . import skillner as _skillner_mod
+        cached = getattr(_skillner_mod, "_nlp", None)
+        if cached is not None:
+            _nlp = cached
+        else:
+            import spacy
+            # Prefer `_lg` for slightly better noun-chunk quality; fall back
+            # to `_sm` which is the minimum viable install documented in
+            # INSTALL.md.
+            try:
+                _nlp = spacy.load("en_core_web_lg")
+            except OSError:
+                _nlp = spacy.load("en_core_web_sm")
+    return _nlp
+
+
+def _candidate_phrases(text: str) -> list[str]:
+    nlp = _get_nlp()
+    doc = nlp(text[:4000])
+    seen: set[str] = set()
+    out: list[str] = []
+    for chunk in doc.noun_chunks:
+        phrase = chunk.text.strip(" ,.;:-").lower()
+        # Skip very short fragments + stopwords-only spans — they lead to
+        # spurious cosine matches against broad skill names.
+        if len(phrase) < 3 or phrase in seen:
+            continue
+        seen.add(phrase)
+        out.append(phrase)
+    return out
+
+
+class SBertLayer(NerLayer):
+    name = "sbert"
+
+    def predict(self, text: str) -> dict[str, float]:
+        if not text.strip():
+            return {}
+        # DB lookup: pgvector cosine against SkillEmbedding. Import Django
+        # models lazily so module import doesn't touch the DB.
+        from pgvector.django import CosineDistance
+
+        from apps.skills.models import Skill, SkillEmbedding
+
+        phrases = _candidate_phrases(text)
+        if not phrases:
+            return {}
+
+        model = _get_model()
+        embeddings = model.encode(phrases, normalize_embeddings=True).tolist()
+
+        out: dict[str, float] = {}
+        # One query per phrase — each hits the HNSW index. 20 phrases × ~2 ms
+        # per query = ~40 ms total, acceptable for on-demand parse.
+        for phrase, vec in zip(phrases, embeddings):
+            top = (
+                SkillEmbedding.objects
+                .annotate(distance=CosineDistance("embedding", vec))
+                .order_by("distance")
+                .select_related("skill")
+                .first()
+            )
+            if top is None:
+                continue
+            # Cosine distance = 1 - cosine similarity for normalized vectors.
+            similarity = 1.0 - float(top.distance)
+            if similarity < _SIM_THRESHOLD:
+                continue
+            name = top.skill.skill_name
+            if similarity > out.get(name, 0.0):
+                out[name] = similarity
+        return out
+
+    def available(self) -> bool:
+        try:
+            import sentence_transformers  # noqa: F401
+            import pgvector  # noqa: F401
+            from apps.skills.models import SkillEmbedding  # noqa: F401
+            return True
+        except Exception:
+            return False
+
+
+layer = SBertLayer()

apps/accounts/ner/skillner.py

@@ -0,0 +1,95 @@
+"""Layer 3: skillNer — rule-based EMSI-taxonomy matcher.
+
+https://github.com/AnasAito/SkillNER — Nov 2021 last release, pure Python,
+works on any spaCy `nlp` object (no version pin). Uses spaCy's PhraseMatcher
+internally so CPU-only and fast.
+
+Gracefully unavailable if its transitive deps (nltk, jellyfish) fail to
+import — the dispatcher's try/except continues with the next layer.
+"""
+from __future__ import annotations
+
+import logging
+
+from . import NerLayer
+
+
+logger = logging.getLogger(__name__)
+
+_extractor = None
+_nlp = None
+_import_error = None
+
+
+def _get_extractor():
+    """Lazy singleton. Import both spaCy + skillNer on first call."""
+    global _extractor, _nlp, _import_error
+    if _extractor is not None:
+        return _extractor
+    if _import_error is not None:
+        # Already attempted and failed — surface the original error so the
+        # dispatcher can log once instead of re-throwing noisily.
+        raise _import_error
+
+    try:
+        import spacy
+        from skillNer.skill_extractor_class import SkillExtractor
+        from skillNer.general_params import SKILL_DB
+        from spacy.matcher import PhraseMatcher
+    except Exception as exc:  # pragma: no cover — env-specific
+        _import_error = exc
+        logger.warning("skillner: unavailable (import failed): %s", exc)
+        raise
+
+    # Prefer `_lg` (word vectors help edge cases) but fall back to `_sm` if
+    # only the smaller model is installed. skillner uses spaCy's PhraseMatcher
+    # which is string-based, so both work; `_lg` is strictly better-quality
+    # when RAM / disk allow.
+    try:
+        _nlp = spacy.load("en_core_web_lg")
+    except OSError:
+        _nlp = spacy.load("en_core_web_sm")
+    # Pass the PhraseMatcher *class*, not an instance: skillNer constructs its
+    # own matcher internally via `self.phraseMatcher(nlp.vocab, attr="LOWER")`,
+    # so handing it an instance raises at construction and disables the layer.
+    _extractor = SkillExtractor(_nlp, SKILL_DB, PhraseMatcher)
+    logger.info("skillner: loaded (spaCy=%s, SKILL_DB=%d entries)",
+                spacy.__version__, len(SKILL_DB))
+    return _extractor
+
+
+class SkillNerLayer(NerLayer):
+    name = "skillner"
+
+    def predict(self, text: str) -> dict[str, float]:
+        if not text.strip():
+            return {}
+        extractor = _get_extractor()
+        annotations = extractor.annotate(text[:4000])
+        out: dict[str, float] = {}
+        results = (annotations or {}).get("results") or {}
+        # full_matches: perfect catalog hits — high confidence.
+        for match in results.get("full_matches") or []:
+            term = (match.get("doc_node_value") or "").strip()
+            if term:
+                out[term] = max(out.get(term, 0.0), 0.95)
+        # ngram_scored: fuzzy catalog hits — skillNer includes its own score.
+        for match in results.get("ngram_scored") or []:
+            term = (match.get("doc_node_value") or "").strip()
+            score = float(match.get("score") or 0.0)
+            if term:
+                out[term] = max(out.get(term, 0.0), score)
+        return out
+
+    def available(self) -> bool:
+        if _import_error is not None:
+            return False
+        try:
+            import skillNer  # noqa: F401
+            import spacy  # noqa: F401
+            return True
+        except Exception:
+            return False
+
+
+layer = SkillNerLayer()

apps/accounts/resume_parser.py

@@ -0,0 +1,456 @@
+"""Resume parsing service — Module 8.
+
+Four-layer NER fallback chain merged on top of a lexical floor:
+
+    Nucha BERT -> jobbert -> SkillNER -> SBERT+pgvector -> lexical (always)
+
+All layers that succeed contribute to the merged output — "merge semantics"
+rather than "first-success". This makes the fallback chain visible in the
+demo and maximises recall for downstream gap analysis: different layers
+catch different phrasings ("ML" vs "machine learning" vs "scikit-learn").
+
+Each layer runs synchronously inside try/except; a layer that raises is logged
+at ERROR and skipped while the rest of the chain continues. The lexical floor
+always fires so the endpoint never returns empty solely because HF models are
+unavailable.
+
+Design constraints:
+
+  * The endpoint contract of ``extract_skills_from_pdf`` is stable: a list
+    of ``SkillPrediction`` dicts. Higher layers enrich confidence for skills
+    the lexical layer already found, and add new skills via alias resolution.
+  * Matching is done against the existing Skill catalog only. We never create
+    new skills from free text — prevents catalog pollution and keeps the
+    recommendation engine grounded in the curated taxonomy.
+  * Proficiency is a heuristic, never an assertion. The user reviews and
+    edits on the Profile page before anything is saved.
+
+Layer selection via env var ``GAPGUIDE_PARSE_LAYERS`` (default is the full
+chain; CI sets this to ``"lexical"`` via conftest.py so tests don't download
+any models). See ~/.claude/plans/okay-plan-for-7a-fluffy-marshmallow.md.
+"""
+from __future__ import annotations
+
+import io
+import logging
+import os
+import re
+from dataclasses import asdict, dataclass
+
+import pdfplumber
+from rapidfuzz import fuzz, process
+
+from apps.skills.models import Skill
+
+
+logger = logging.getLogger(__name__)
+
+# Layer order — the dispatcher runs in this sequence. Merging is order-agnostic
+# but the order here drives the "first to register a given skill wins the
+# proficiency heuristic" rule. Lexical last (it already has the best local
+# context), but we guarantee it runs last anyway in _predict_skills_from_text.
+_DEFAULT_LAYERS = "nucha,jobbert,skillner,sbert,lexical"
+
+
+MAX_PDF_BYTES = 5 * 1024 * 1024  # 5 MB — UCP students' CVs fit easily.
+MAX_TEXT_CHARS = 60_000          # defends the downstream matcher.
+
+# Rough heuristic — the parser is an *augmentation* layer, so we cap signals
+# below 70 so the user always has room to raise after review.
+_DEFAULT_PROFICIENCY = 55
+_STRONG_SIGNAL_PROFICIENCY = 70
+
+# Fuzzy layer is per-token (not partial_ratio against the full doc), so the
+# threshold is genuinely "this word is essentially a typo of the skill name".
+# Anything lower would flood the output with false positives like
+# partial_ratio("python", "sourdough") > 0.5.
+_FUZZY_TOKEN_SCORE = 88
+_FUZZY_MIN_SKILL_LEN = 5   # 'Go', 'R', 'SQL' never go through fuzzy path
+
+# Terms that indicate hands-on experience → pushes proficiency toward the top.
+_EXPERIENCE_MARKERS = re.compile(
+    r"\b(?:expert|advanced|proficien[tc]y?|senior|lead|architect|years?|yrs?)\b",
+    re.IGNORECASE,
+)
+
+# Terms that hint at entry level → pulls proficiency down.
+_NOVICE_MARKERS = re.compile(
+    r"\b(?:beginner|junior|intro(?:duction)?|basic|elementary|familiar with)\b",
+    re.IGNORECASE,
+)
+
+# Rank by *signal strength*, NOT numeric proficiency. NOVICE=40 is numerically
+# less than DEFAULT=55 but carries a stronger claim ("beginner Python" beats
+# silence), so it should win during window aggregation.
+_NOVICE_PROFICIENCY = 40
+_PROFICIENCY_RANK = {
+    _STRONG_SIGNAL_PROFICIENCY: 2,
+    _NOVICE_PROFICIENCY: 1,
+    _DEFAULT_PROFICIENCY: 0,
+}
+
+# Per-layer calibration coefficient applied before the max() merge in
+# _predict_skills_from_text. Each layer emits [0,1] from a different
+# distribution — softmax (Nucha/JobBERT), cosine similarity above 0.65 threshold
+# (SBERT), hardcoded 0.95 / rapidfuzz ratio (lexical). Raw max lets lexical's
+# hardcoded 0.95 outweigh a genuine model hit of 0.92. Values are heuristic —
+# a Platt-scaling rebuild from labelled data is out of FYP scope, but these at
+# least stop the hardcoded layers from dominating live model output.
+_LAYER_CALIBRATION = {
+    'nucha': 1.0,
+    'jobbert': 1.0,
+    'skillner': 0.90,
+    'sbert': 0.85,
+    'lexical': 0.95,
+}
+
+
+class ResumeParseError(ValueError):
+    """Raised for malformed or oversized inputs."""
+
+
+@dataclass
+class SkillPrediction:
+    skill_id: int
+    skill_name: str
+    proficiency: int
+    confidence: float
+    matched_span: str
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def _extract_text(pdf_bytes: bytes) -> str:
+    if len(pdf_bytes) > MAX_PDF_BYTES:
+        raise ResumeParseError(
+            f"Resume exceeds the {MAX_PDF_BYTES // 1024 // 1024} MB upload limit."
+        )
+    if not pdf_bytes:
+        raise ResumeParseError("Empty upload.")
+
+    try:
+        with pdfplumber.open(io.BytesIO(pdf_bytes)) as pdf:
+            pages = []
+            for page in pdf.pages:
+                text = page.extract_text() or ""
+                pages.append(text)
+                if sum(len(p) for p in pages) > MAX_TEXT_CHARS:
+                    break
+            full_text = "\n".join(pages)
+    except Exception as exc:
+        # pdfplumber raises a grab-bag of exceptions for corrupt PDFs; treat
+        # them all as user input errors rather than 500s.
+        raise ResumeParseError(f"Could not read PDF: {exc}") from exc
+
+    if not full_text.strip():
+        raise ResumeParseError(
+            "No text could be extracted. If your CV is a scanned image, "
+            "re-export it as a text-based PDF."
+        )
+    return full_text[:MAX_TEXT_CHARS]
+
+
+def _classify_proficiency(context: str) -> tuple[int, float]:
+    """Return (proficiency, confidence_boost) from surrounding context.
+
+    A short window around the matched span is all we get — this is purposely
+    coarse. Higher layers can refine with a real classifier later.
+    """
+    if _EXPERIENCE_MARKERS.search(context):
+        return _STRONG_SIGNAL_PROFICIENCY, 0.10
+    if _NOVICE_MARKERS.search(context):
+        return _NOVICE_PROFICIENCY, 0.05
+    return _DEFAULT_PROFICIENCY, 0.0
+
+
+def _classify_aggregated(contexts: list[str]) -> tuple[int, float]:
+    """Pick the strongest signal across all window contexts for a single skill.
+
+    Short-circuits on STRONG (the ceiling). Ranks by _PROFICIENCY_RANK, not by
+    raw proficiency value, so NOVICE ("beginner X") beats DEFAULT (silence)
+    even though NOVICE=40 < DEFAULT=55.
+    """
+    best = (_DEFAULT_PROFICIENCY, 0.0)
+    best_rank = 0
+    for ctx in contexts:
+        prof, boost = _classify_proficiency(ctx)
+        rank = _PROFICIENCY_RANK.get(prof, 0)
+        if rank > best_rank:
+            best, best_rank = (prof, boost), rank
+            if rank == 2:  # STRONG — can't improve further.
+                break
+    return best
+
+
+def _windows_for(text: str, pattern: str, context_chars: int = 60) -> list[str]:
+    """Yield ±context_chars windows around every match of `pattern` in text."""
+    windows = []
+    for match in re.finditer(pattern, text.lower()):
+        start = max(0, match.start() - context_chars)
+        end = min(len(text), match.end() + context_chars)
+        windows.append(text[start:end])
+    return windows
+
+
+_TOKEN_RE = re.compile(r"[A-Za-z][A-Za-z0-9+#.\-]{2,}")
+
+
+def _candidate_matches(text: str, skills: list[Skill]) -> dict[int, dict]:
+    """Return {skill_id: {'confidence', 'proficiency', 'matched_span'}} for
+    every catalog skill that appears in the text.
+
+    Two passes:
+      1. Exact (case-insensitive) boundary-aware substring hit → high
+         confidence (0.95). We do NOT include '.' in the boundary character
+         class because tech names like "Node.js" already round-trip through
+         ``re.escape`` and sentence-final punctuation like "... SQL." must
+         still match.
+      2. Token-level fuzzy match — for each token in the document that's
+         long enough, rapidfuzz.fuzz.ratio against the catalog. ``partial_
+         ratio`` was rejected because it false-positives aggressively
+         ("python" vs "sourdough" scored ~0.5). Per-token ``ratio`` with a
+         high threshold (88) only fires on near-typos.
+    """
+    hits: dict[int, dict] = {}
+
+    for skill in skills:
+        name = skill.skill_name.strip()
+        if not name:
+            continue
+        needle = name.lower()
+        # Word-boundary exact match — '\b' handles punctuation around
+        # identifier-like tech names. '.' is intentionally excluded from the
+        # boundary class so "SQL." at end-of-sentence still matches.
+        pattern = r"(?<![A-Za-z0-9+#\-])" + re.escape(needle) + r"(?![A-Za-z0-9+#\-])"
+        windows = _windows_for(text, pattern)
+        if windows:
+            prof, boost = _classify_aggregated(windows)
+            # First window is kept as the human-readable matched_span — the
+            # strongest-signal window may be far away, and the first occurrence
+            # is what the reviewer will visually scan for.
+            hits[skill.id] = {
+                'confidence': round(min(0.95 + boost, 0.99), 3),
+                'proficiency': prof,
+                'matched_span': windows[0].strip(),
+            }
+
+    # Fuzzy pass: build the document's token set once, then for each unmatched
+    # skill find its best-matching token (rapidfuzz.process.extractOne).
+    tokens = list({m.group(0) for m in _TOKEN_RE.finditer(text)})
+    if not tokens:
+        return hits
+
+    for skill in skills:
+        if skill.id in hits:
+            continue
+        name = skill.skill_name.strip()
+        if len(name) < _FUZZY_MIN_SKILL_LEN:
+            # Short names ('Go', 'R', 'SQL') only travel the exact path.
+            continue
+        candidate = process.extractOne(
+            name.lower(),
+            [t.lower() for t in tokens],
+            scorer=fuzz.ratio,
+            score_cutoff=_FUZZY_TOKEN_SCORE,
+        )
+        if candidate is None:
+            continue
+        _, score, idx = candidate
+        hits[skill.id] = {
+            'confidence': round(score / 100.0, 3),
+            'proficiency': _DEFAULT_PROFICIENCY,
+            'matched_span': tokens[idx],
+        }
+
+    return hits
+
+
+def _load_layer(layer_name: str):
+    """Lazy-import a layer module by name. Returns None if import fails.
+
+    Done this way (rather than an eager registry) so a CI run pinned to
+    ``GAPGUIDE_PARSE_LAYERS=lexical`` never imports transformers/torch.
+    """
+    try:
+        # `apps.accounts.ner.<name>` — lives next to this module.
+        mod = __import__(
+            f"apps.accounts.ner.{layer_name}",
+            fromlist=["layer"],
+        )
+        return getattr(mod, "layer", None)
+    except Exception as exc:
+        logger.warning("ner.%s: import failed, skipping (%s)", layer_name, exc)
+        return None
+
+
+def _enabled_layers() -> list[str]:
+    raw = os.environ.get("GAPGUIDE_PARSE_LAYERS", _DEFAULT_LAYERS)
+    out = [s.strip() for s in raw.split(",") if s.strip()]
+    # Always guarantee lexical at the end — contract says the floor fires.
+    if "lexical" not in out:
+        out.append("lexical")
+    return out
+
+
+def _find_span_for(text: str, skill_name: str) -> tuple[int, str]:
+    """Search the text for `skill_name` and derive (proficiency, matched_span).
+
+    Used to enrich non-lexical layer hits with the same surrounding-context
+    proficiency heuristic the lexical layer uses. If the skill name isn't
+    literally in the text (the layer inferred it from a paraphrase), fall
+    back to the default proficiency + empty span.
+
+    Multi-window aggregation: if the skill appears multiple times, the
+    strongest *signal* across windows wins (STRONG > NOVICE > DEFAULT).
+    """
+    needle = re.escape(skill_name.lower())
+    pattern = r"(?<![A-Za-z0-9+#\-])" + needle + r"(?![A-Za-z0-9+#\-])"
+    windows = _windows_for(text, pattern)
+    if not windows:
+        return _DEFAULT_PROFICIENCY, ''
+    prof, _ = _classify_aggregated(windows)
+    return prof, windows[0].strip()
+
+
+def _resolve_alias(alias: str, skills_by_lower: dict, all_skills: list[Skill]) -> Skill | None:
+    """Map a free-text alias to a canonical Skill row.
+
+    Exact match (case-insensitive) -> fuzzy match via rapidfuzz using the
+    same threshold as the lexical layer. Returns None if nothing confident
+    enough is found. Aliases too short to fuzzy-match just require an exact
+    hit; keeps 'Go' and 'R' from matching arbitrary noun phrases.
+    """
+    if not alias:
+        return None
+    key = alias.strip().lower()
+    hit = skills_by_lower.get(key)
+    if hit is not None:
+        return hit
+    if len(key) < _FUZZY_MIN_SKILL_LEN:
+        return None
+    candidate = process.extractOne(
+        key,
+        list(skills_by_lower.keys()),
+        scorer=fuzz.ratio,
+        score_cutoff=_FUZZY_TOKEN_SCORE,
+    )
+    if candidate is None:
+        return None
+    matched_name, _, _ = candidate
+    return skills_by_lower.get(matched_name)
+
+
+def _predict_skills_from_text(text: str) -> tuple[dict[int, dict], list[str]]:
+    """Run enabled NER layers against `text` and merge their hits.
+
+    Returns (hits_by_skill_id, fired_layers):
+      - hits_by_skill_id: {skill_id: {confidence, proficiency, matched_span}}
+      - fired_layers: layers that actually returned results (in order)
+
+    Each layer runs synchronously. A layer that raises during predict() is
+    logged at ERROR (with traceback) and skipped — the rest of the chain
+    continues. (Import failures are caught earlier in _load_layer and logged
+    at WARNING.) If ALL layers fail, the endpoint still returns 200 with the
+    lexical-floor output (since lexical is always run).
+    """
+    skills = list(Skill.objects.all().only('id', 'skill_name'))
+    skills_by_lower = {s.skill_name.lower(): s for s in skills}
+
+    hits: dict[int, dict] = {}
+    fired: list[str] = []
+
+    for layer_name in _enabled_layers():
+        layer = _load_layer(layer_name)
+        if layer is None or not layer.available():
+            continue
+        try:
+            # Run synchronously. A previous version ran each layer in a
+            # ThreadPoolExecutor for timeout support, but Django's ORM uses
+            # thread-local connections — the new thread never saw the test
+            # transaction's uncommitted rows, so the lexical/sbert layers
+            # found nothing under pytest-django. HF client libraries already
+            # apply their own request timeouts, so dropping the local one
+            # costs us only a theoretical hang on a misbehaving custom layer.
+            layer_out = layer.predict(text)
+        except Exception as exc:
+            # Keep the catch broad (a flaky HF layer must never 500 the upload)
+            # but log at ERROR with the traceback — the always-on net that makes
+            # a silently-skipped layer (e.g. a wiring/construction bug) visible
+            # in the logs instead of vanishing.
+            logger.error(
+                "ner.%s: raised %s, skipping", layer_name, exc, exc_info=True,
+            )
+            continue
+
+        if not layer_out:
+            continue
+        fired.append(layer_name)
+
+        calibration = _LAYER_CALIBRATION.get(layer_name, 1.0)
+        for alias, conf in layer_out.items():
+            skill = _resolve_alias(alias, skills_by_lower, skills)
+            if skill is None:
+                continue
+            existing = hits.get(skill.id)
+            # Calibrate per-layer so a 0.92 softmax isn't dominated by a
+            # hardcoded lexical 0.95. Cap below 1.0 to keep downstream plots
+            # away from the edge of the [0,1] axis.
+            conf_f = round(min(float(conf) * calibration, 0.99), 3)
+            if existing is None:
+                prof, span = _find_span_for(text, skill.skill_name)
+                hits[skill.id] = {
+                    'confidence': conf_f,
+                    'proficiency': prof,
+                    'matched_span': span,
+                }
+            elif conf_f > existing['confidence']:
+                existing['confidence'] = conf_f
+
+    return hits, fired
+
+
+def extract_skills_from_pdf(pdf_bytes: bytes) -> list[dict]:
+    """Parse a resume PDF and return ordered, catalog-resolved skill predictions.
+
+    Kept as a list-only return to preserve the MVP test contract. The view
+    uses :func:`parse_resume_envelope` instead, which also carries the list
+    of layers that fired (the dispatcher's `parser_version`).
+    """
+    env = parse_resume_envelope(pdf_bytes)
+    return env['skills']
+
+
+def parse_resume_envelope(pdf_bytes: bytes) -> dict:
+    """Full response envelope: ``{'skills': [...], 'parser_version': [...]}``.
+
+    `parser_version` is a list of layer names so the frontend can render a
+    real "which layers fired" chip sequence (`["nucha", "lexical"]`) rather
+    than the MVP's opaque `"mvp-lexical-v1"` string.
+    """
+    text = _extract_text(pdf_bytes)
+    scored, fired = _predict_skills_from_text(text)
+    if not scored:
+        return {'skills': [], 'parser_version': fired}
+
+    skill_lookup = {
+        s.id: s for s in Skill.objects.filter(id__in=scored.keys())
+    }
+    predictions: list[SkillPrediction] = []
+    for skill_id, data in scored.items():
+        skill = skill_lookup.get(skill_id)
+        if skill is None:
+            continue
+        predictions.append(SkillPrediction(
+            skill_id=skill_id,
+            skill_name=skill.skill_name,
+            proficiency=int(data['proficiency']),
+            confidence=float(data['confidence']),
+            matched_span=str(data['matched_span'])[:200],
+        ))
+
+    predictions.sort(key=lambda p: (-p.confidence, p.skill_name))
+    return {
+        'skills': [p.to_dict() for p in predictions],
+        'parser_version': fired,
+    }

apps/accounts/serializers.py

@@ -0,0 +1,112 @@
+from django.contrib.auth import authenticate
+from django.contrib.auth.password_validation import validate_password as django_validate_password
+from django.core.exceptions import ValidationError as DjangoValidationError
+from drf_spectacular.utils import extend_schema_field
+from rest_framework import serializers
+from .models import User, UserProfile
+from apps.skills.models import UserSkill
+from apps.skills.serializers import UserSkillSerializer
+
+
+class RegisterSerializer(serializers.ModelSerializer):
+    password_confirm = serializers.CharField(write_only=True)
+
+    class Meta:
+        model = User
+        fields = ['name', 'email', 'password', 'password_confirm']
+        extra_kwargs = {
+            'password': {'write_only': True},
+        }
+
+    def validate(self, attrs):
+        if attrs['password'] != attrs['password_confirm']:
+            raise serializers.ValidationError({"password": "Passwords do not match."})
+        return attrs
+
+    def validate_email(self, value):
+        # Case-insensitive uniqueness: store lowercase so `Foo@X.com` and
+        # `foo@x.com` cannot both register, and login is case-insensitive too.
+        normalized = value.strip().lower()
+        if User.objects.filter(email__iexact=normalized).exists():
+            raise serializers.ValidationError("A user with this email already exists.")
+        return normalized
+
+    def validate_password(self, value):
+        # Run Django's configured AUTH_PASSWORD_VALIDATORS (min-length, common,
+        # numeric, user-similarity). Without this call the settings list is dead
+        # config.
+        try:
+            django_validate_password(value)
+        except DjangoValidationError as exc:
+            raise serializers.ValidationError(list(exc.messages))
+        return value
+
+    def create(self, validated_data):
+        validated_data.pop('password_confirm')
+        email = validated_data['email']
+        user = User.objects.create_user(
+            username=email,
+            email=email,
+            name=validated_data.get('name', ''),
+            password=validated_data['password'],
+            role_type='STUDENT'
+        )
+        return user
+
+
+class LoginSerializer(serializers.Serializer):
+    email = serializers.EmailField(write_only=True)
+    password = serializers.CharField(write_only=True)
+
+    def validate(self, attrs):
+        # Normalize to match the lowercase username stored at registration.
+        email = (attrs.get('email') or '').strip().lower()
+        user = authenticate(
+            request=self.context.get('request'),
+            username=email,
+            password=attrs.get('password')
+        )
+
+        if not user:
+            raise serializers.ValidationError("Invalid credentials.")
+
+        if not user.is_active:
+            raise serializers.ValidationError("User account is disabled.")
+
+        return user
+
+
+class UserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ['id', 'name', 'email', 'role_type', 'created_at']
+        read_only_fields = ['id', 'name', 'email', 'role_type', 'created_at']
+
+
+class UserProfileSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = UserProfile
+        fields = ['degree', 'semester', 'interests', 'bio', 'updated_at']
+        read_only_fields = ['updated_at']
+
+
+class ProfileWithSkillsSerializer(serializers.Serializer):
+    user = serializers.SerializerMethodField()
+    profile = serializers.SerializerMethodField()
+    skills = serializers.SerializerMethodField()
+
+    @extend_schema_field(UserSerializer)
+    def get_user(self, obj):
+        return UserSerializer(obj).data
+
+    @extend_schema_field(UserProfileSerializer)
+    def get_profile(self, obj):
+        try:
+            return UserProfileSerializer(obj.profile).data
+        except UserProfile.DoesNotExist:
+            return {}
+
+    @extend_schema_field(UserSkillSerializer(many=True))
+    def get_skills(self, obj):
+        user_skills = UserSkill.objects.filter(user=obj).select_related('skill')
+        return UserSkillSerializer(user_skills, many=True).data

apps/accounts/tests/test_auth.py

@@ -0,0 +1,140 @@
+import pytest
+from rest_framework.test import APIClient
+
+pytestmark = pytest.mark.django_db
+
+VALID_USER = {
+    'name': 'Test User',
+    'email': 'test@example.com',
+    'password': 'TestPass123!',
+    'password_confirm': 'TestPass123!'
+}
+
+REGISTER_URL = '/api/auth/register/'
+LOGIN_URL = '/api/auth/login/'
+LOGOUT_URL = '/api/auth/logout/'
+ME_URL = '/api/auth/me/'
+
+
+@pytest.fixture
+def api_client():
+    return APIClient()
+
+
+@pytest.fixture
+def user_data():
+    return VALID_USER.copy()
+
+
+@pytest.fixture
+def registered_user(api_client, user_data):
+    """Register a user and return the response data."""
+    response = api_client.post(REGISTER_URL, data=user_data, format='json')
+    return response.data
+
+
+class TestRegistration:
+    def test_valid_registration(self, api_client, user_data):
+        """TC-01: Valid registration returns 201 with tokens."""
+        response = api_client.post(REGISTER_URL, data=user_data, format='json')
+        assert response.status_code == 201
+        assert 'access' in response.data
+        assert 'refresh' in response.data
+        assert 'user' in response.data
+        assert response.data['user']['email'] == user_data['email']
+
+    def test_duplicate_email(self, api_client, user_data):
+        """TC-02: Duplicate email returns 400."""
+        api_client.post(REGISTER_URL, data=user_data, format='json')
+        response = api_client.post(REGISTER_URL, data=user_data, format='json')
+        assert response.status_code == 400
+
+    def test_password_mismatch(self, api_client, user_data):
+        """Password mismatch returns 400."""
+        user_data['password_confirm'] = 'DifferentPassword!'
+        response = api_client.post(REGISTER_URL, data=user_data, format='json')
+        assert response.status_code == 400
+
+    def test_missing_fields(self, api_client):
+        """Missing required fields returns 400."""
+        response = api_client.post(REGISTER_URL, data={'email': 'x@x.com'}, format='json')
+        assert response.status_code == 400
+
+
+class TestLogin:
+    def test_valid_login(self, api_client, user_data, registered_user):
+        """TC-03: Valid login returns 200 with tokens."""
+        login_data = {'email': user_data['email'], 'password': user_data['password']}
+        response = api_client.post(LOGIN_URL, data=login_data, format='json')
+        assert response.status_code == 200
+        assert 'access' in response.data
+        assert 'refresh' in response.data
+
+    def test_invalid_credentials(self, api_client, user_data, registered_user):
+        """TC-04: Wrong password returns 400."""
+        login_data = {'email': user_data['email'], 'password': 'WrongPassword!'}
+        response = api_client.post(LOGIN_URL, data=login_data, format='json')
+        assert response.status_code == 400
+
+
+class TestMe:
+    def test_me_without_token(self, api_client):
+        """GET /me/ without token returns 401."""
+        response = api_client.get(ME_URL)
+        assert response.status_code == 401
+
+    def test_get_me(self, api_client, user_data, registered_user):
+        """Authenticated GET /me/ returns user data."""
+        access_token = registered_user['access']
+        api_client.credentials(HTTP_AUTHORIZATION='Bearer ' + access_token)
+        response = api_client.get(ME_URL)
+        assert response.status_code == 200
+        assert response.data['email'] == user_data['email']
+
+
+class TestLoginThrottle:
+    def test_login_rate_limit_blocks_after_threshold(
+        self, api_client, user_data, registered_user,
+    ):
+        """Login endpoint is throttled at 10/minute — verify the 11th
+        attempt is rejected with 429, regardless of credentials."""
+        bad = {'email': user_data['email'], 'password': 'nope'}
+        # Burn through the limit with invalid credentials (400 per attempt).
+        for _ in range(10):
+            r = api_client.post(LOGIN_URL, data=bad, format='json')
+            assert r.status_code in (400, 401)
+        # 11th must be throttled.
+        r = api_client.post(LOGIN_URL, data=bad, format='json')
+        assert r.status_code == 429
+
+
+class TestLogout:
+    def test_logout(self, api_client, user_data, registered_user):
+        """Logout blacklists refresh token, returns 204."""
+        access_token = registered_user['access']
+        refresh_token = registered_user['refresh']
+
+        api_client.credentials(HTTP_AUTHORIZATION='Bearer ' + access_token)
+        response = api_client.post(
+            LOGOUT_URL,
+            data={'refresh_token': refresh_token},
+            format='json'
+        )
+        assert response.status_code == 204
+
+
+class TestRegistrationRace:
+    def test_concurrent_email_race_returns_400(self, api_client, user_data):
+        """F2: a concurrent case-variant registration can bypass the
+        case-insensitive validate_email check; the DB unique index then raises
+        IntegrityError. The view must surface a clean 400 keyed on `email`,
+        not an unhandled 500."""
+        from unittest.mock import patch
+        from django.db import IntegrityError
+        with patch(
+            'apps.accounts.serializers.RegisterSerializer.save',
+            side_effect=IntegrityError,
+        ):
+            response = api_client.post(REGISTER_URL, data=user_data, format='json')
+        assert response.status_code == 400
+        assert 'email' in response.data

apps/accounts/tests/test_ner_dispatcher.py

@@ -0,0 +1,196 @@
+"""Dispatcher tests for the four-layer NER fallback chain.
+
+Covers:
+  * Merge semantics — outputs from multiple layers union into one alias dict.
+  * Per-layer failures are silently skipped; remaining layers still contribute.
+  * If every layer raises, the endpoint still returns 200 with the lexical
+    floor output (since lexical is always appended to the enabled list).
+"""
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+
+from apps.skills.models import Skill
+
+
+pytestmark = pytest.mark.django_db
+
+
+@pytest.fixture
+def catalog():
+    py = Skill.objects.create(skill_name='Python', category='Programming',
+                              difficulty_level='BEGINNER')
+    sql = Skill.objects.create(skill_name='SQL', category='Database',
+                               difficulty_level='BEGINNER')
+    react = Skill.objects.create(skill_name='React', category='Frontend',
+                                 difficulty_level='BEGINNER')
+    return {'python': py, 'sql': sql, 'react': react}
+
+
+def _make_layer(name, predictions):
+    """Build a lightweight object that quacks like NerLayer."""
+    class _Fake:
+        pass
+    fake = _Fake()
+    fake.name = name
+    fake.predict = lambda _text: predictions
+    fake.available = lambda: True
+    return fake
+
+
+def test_merge_semantics_union_hits_from_multiple_layers(catalog):
+    from apps.accounts.resume_parser import _predict_skills_from_text
+
+    layers = {
+        'nucha': _make_layer('nucha', {'Python': 0.92}),
+        'jobbert': _make_layer('jobbert', {'SQL': 0.81}),
+        'lexical': _make_layer('lexical', {'React': 0.95}),
+    }
+
+    with patch('apps.accounts.resume_parser._load_layer', side_effect=layers.get), \
+         patch('apps.accounts.resume_parser._enabled_layers',
+               return_value=['nucha', 'jobbert', 'lexical']):
+        hits, fired = _predict_skills_from_text("Python SQL React")
+
+    assert fired == ['nucha', 'jobbert', 'lexical']
+    skill_ids = {catalog['python'].id, catalog['sql'].id, catalog['react'].id}
+    assert set(hits) == skill_ids
+
+
+def test_max_confidence_kept_when_layers_agree(catalog):
+    from apps.accounts.resume_parser import _predict_skills_from_text
+
+    layers = {
+        'nucha': _make_layer('nucha', {'Python': 0.70}),
+        'jobbert': _make_layer('jobbert', {'Python': 0.92}),  # higher
+        'lexical': _make_layer('lexical', {'Python': 0.85}),
+    }
+    with patch('apps.accounts.resume_parser._load_layer', side_effect=layers.get), \
+         patch('apps.accounts.resume_parser._enabled_layers',
+               return_value=['nucha', 'jobbert', 'lexical']):
+        hits, _ = _predict_skills_from_text("Python Python Python")
+
+    py_id = catalog['python'].id
+    # round(min(0.92, 0.99), 3) == 0.92
+    assert hits[py_id]['confidence'] == 0.92
+
+
+def test_failing_layer_is_skipped_silently(catalog):
+    """One layer raises — dispatcher logs an error and continues with others."""
+    from apps.accounts.resume_parser import _predict_skills_from_text
+
+    class _Exploding:
+        name = 'nucha'
+        def predict(self, _): raise RuntimeError("HF hub is down")
+        def available(self): return True
+
+    layers = {
+        'nucha': _Exploding(),
+        'lexical': _make_layer('lexical', {'Python': 0.95}),
+    }
+    with patch('apps.accounts.resume_parser._load_layer', side_effect=layers.get), \
+         patch('apps.accounts.resume_parser._enabled_layers',
+               return_value=['nucha', 'lexical']):
+        hits, fired = _predict_skills_from_text("Python rocks")
+
+    assert fired == ['lexical']  # nucha dropped silently
+    assert catalog['python'].id in hits
+
+
+def test_all_layers_fail_falls_back_to_empty_but_no_exception(catalog):
+    """If literally every layer raises, dispatcher returns (empty, empty) and
+    the endpoint still 200s — never propagates the layer failures."""
+    from apps.accounts.resume_parser import _predict_skills_from_text
+
+    class _Exploding:
+        def __init__(self, name): self.name = name
+        def predict(self, _): raise RuntimeError("boom")
+        def available(self): return True
+
+    layers = {
+        'nucha': _Exploding('nucha'),
+        'lexical': _Exploding('lexical'),
+    }
+    with patch('apps.accounts.resume_parser._load_layer', side_effect=layers.get), \
+         patch('apps.accounts.resume_parser._enabled_layers',
+               return_value=['nucha', 'lexical']):
+        hits, fired = _predict_skills_from_text("Python SQL")
+
+    assert hits == {}
+    assert fired == []
+
+
+def test_alias_resolution_fuzzy_matches_typos(catalog):
+    """A non-lexical layer returning a near-miss alias still resolves to the
+    catalog row via rapidfuzz."""
+    from apps.accounts.resume_parser import _predict_skills_from_text
+
+    # "phython" → "Python" via rapidfuzz ratio ~92 (above 88 threshold).
+    # A two-letter transposition like "pyhton" only scores ~83 — on the
+    # wrong side of the cutoff — so pick a typo that lands decisively above it.
+    layers = {
+        'nucha': _make_layer('nucha', {'phython': 0.90}),
+        'lexical': _make_layer('lexical', {}),
+    }
+    with patch('apps.accounts.resume_parser._load_layer', side_effect=layers.get), \
+         patch('apps.accounts.resume_parser._enabled_layers',
+               return_value=['nucha', 'lexical']):
+        hits, _ = _predict_skills_from_text("phython is my favourite")
+
+    assert catalog['python'].id in hits
+
+
+def test_alias_resolution_drops_unknown_skills(catalog):
+    """A layer claiming 'COBOL' when the catalog has no COBOL row → ignored."""
+    from apps.accounts.resume_parser import _predict_skills_from_text
+
+    layers = {
+        'nucha': _make_layer('nucha', {'COBOL': 0.90, 'Brainfuck': 0.85}),
+        'lexical': _make_layer('lexical', {}),
+    }
+    with patch('apps.accounts.resume_parser._load_layer', side_effect=layers.get), \
+         patch('apps.accounts.resume_parser._enabled_layers',
+               return_value=['nucha', 'lexical']):
+        hits, _ = _predict_skills_from_text("COBOL Brainfuck")
+
+    assert hits == {}
+
+
+def test_layer_calibration_flips_max_when_lexical_outweighs_model(catalog):
+    """Per-layer calibration coefficients prevent lexical's hardcoded 0.95 from
+    dominating a genuine model hit of 0.92. With _LAYER_CALIBRATION:
+        lexical 0.95 × 0.95 = 0.9025
+        nucha   0.92 × 1.00 = 0.92
+    Nucha now wins. Without calibration lexical would win at 0.95.
+    """
+    from apps.accounts.resume_parser import _predict_skills_from_text
+
+    layers = {
+        'nucha': _make_layer('nucha', {'Python': 0.92}),
+        'lexical': _make_layer('lexical', {'Python': 0.95}),
+    }
+    with patch('apps.accounts.resume_parser._load_layer', side_effect=layers.get), \
+         patch('apps.accounts.resume_parser._enabled_layers',
+               return_value=['nucha', 'lexical']):
+        hits, _ = _predict_skills_from_text("Python project")
+
+    py_id = catalog['python'].id
+    # Nucha's 0.92 (uncalibrated ×1.0) beats lexical's 0.9025 (0.95 ×0.95).
+    assert hits[py_id]['confidence'] == 0.92
+
+
+def test_parser_version_only_lists_layers_that_returned_hits(catalog):
+    """A layer that runs but returns {} is NOT in parser_version."""
+    from apps.accounts.resume_parser import _predict_skills_from_text
+
+    layers = {
+        'nucha': _make_layer('nucha', {}),
+        'lexical': _make_layer('lexical', {'Python': 0.95}),
+    }
+    with patch('apps.accounts.resume_parser._load_layer', side_effect=layers.get), \
+         patch('apps.accounts.resume_parser._enabled_layers',
+               return_value=['nucha', 'lexical']):
+        _, fired = _predict_skills_from_text("Python")
+    assert fired == ['lexical']

apps/accounts/tests/test_ner_layers.py

@@ -0,0 +1,221 @@
+"""Per-layer unit tests for Module 8 NER layers.
+
+Each layer's heavy model is mocked so CI doesn't pull ~1 GB of BERT weights.
+Runtime integration with real models is covered by
+test_resume_parser_integration.py (gated on GAPGUIDE_ML_SMOKE=1).
+"""
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# Nucha layer
+# ---------------------------------------------------------------------------
+class TestNuchaLayer:
+    def test_predict_extracts_hard_and_soft_skills(self):
+        """Pipeline returns HSKILL/SSKILL spans → alias dict keyed on span."""
+        from apps.accounts.ner import nucha
+
+        fake_pipeline = MagicMock(return_value=[
+            {'entity_group': 'HSKILL', 'score': 0.93, 'word': 'Python',
+             'start': 0, 'end': 6},
+            {'entity_group': 'HSKILL', 'score': 0.88, 'word': 'SQL',
+             'start': 10, 'end': 13},
+            {'entity_group': 'SSKILL', 'score': 0.71, 'word': 'teamwork',
+             'start': 20, 'end': 28},
+            # Non-skill tokens must be dropped.
+            {'entity_group': 'O', 'score': 0.99, 'word': 'and',
+             'start': 14, 'end': 17},
+        ])
+
+        with patch.object(nucha, '_pipeline', fake_pipeline):
+            out = nucha.layer.predict("Python SQL and teamwork")
+
+        assert out == {
+            'Python': pytest.approx(0.93),
+            'SQL': pytest.approx(0.88),
+            'teamwork': pytest.approx(0.71),
+        }
+
+    def test_empty_text_returns_empty(self):
+        from apps.accounts.ner import nucha
+        with patch.object(nucha, '_pipeline', MagicMock()) as m:
+            assert nucha.layer.predict("") == {}
+            m.assert_not_called()  # shortcut before the pipeline runs
+
+    def test_duplicate_spans_keep_max_confidence(self):
+        from apps.accounts.ner import nucha
+        fake = MagicMock(return_value=[
+            {'entity_group': 'HSKILL', 'score': 0.5, 'word': 'Python'},
+            {'entity_group': 'HSKILL', 'score': 0.9, 'word': 'Python'},
+            {'entity_group': 'HSKILL', 'score': 0.7, 'word': 'Python'},
+        ])
+        with patch.object(nucha, '_pipeline', fake):
+            out = nucha.layer.predict("Python Python Python")
+        assert out == {'Python': pytest.approx(0.9)}
+
+
+# ---------------------------------------------------------------------------
+# JobBERT layer
+# ---------------------------------------------------------------------------
+class TestJobBertLayer:
+    def test_predict_accepts_bio_labels(self):
+        from apps.accounts.ner import jobbert
+
+        fake = MagicMock(return_value=[
+            {'entity_group': 'Skill', 'score': 0.87, 'word': 'React'},
+            {'entity_group': 'Skill', 'score': 0.81, 'word': 'Docker'},
+            # Non-skill label dropped.
+            {'entity_group': 'O', 'score': 0.99, 'word': 'the'},
+        ])
+        with patch.object(jobbert, '_pipeline', fake):
+            out = jobbert.layer.predict("React Docker the project")
+        assert out == {'React': pytest.approx(0.87), 'Docker': pytest.approx(0.81)}
+
+    def test_label_casing_is_ignored(self):
+        from apps.accounts.ner import jobbert
+        fake = MagicMock(return_value=[
+            {'entity_group': 'SKILL', 'score': 0.9, 'word': 'AWS'},
+            {'entity_group': 'skill', 'score': 0.8, 'word': 'GCP'},
+        ])
+        with patch.object(jobbert, '_pipeline', fake):
+            out = jobbert.layer.predict("AWS GCP")
+        assert 'AWS' in out and 'GCP' in out
+
+    def test_multitoken_skill_is_merged_via_offsets(self):
+        """F-NER-FRAG: with character offsets, a skill's B token + adjacent I
+        tokens re-stitch into one term (jjzha's suffix-less BIO labels stop
+        aggregation_strategy='simple' from doing this). Two separate B-started
+        skills stay distinct even when adjacent."""
+        from apps.accounts.ner import jobbert
+
+        text = "machine learning and Python"
+        fake = MagicMock(return_value=[
+            {'entity_group': 'B', 'score': 0.90, 'word': 'machine',
+             'start': 0, 'end': 7},
+            {'entity_group': 'I', 'score': 0.80, 'word': 'learning',
+             'start': 8, 'end': 16},  # adjacent (gap == 1) → merges
+            {'entity_group': 'B', 'score': 0.95, 'word': 'Python',
+             'start': 21, 'end': 27},  # new B → stays separate
+        ])
+        with patch.object(jobbert, '_pipeline', fake):
+            out = jobbert.layer.predict(text)
+        assert out == {
+            'machine learning': pytest.approx(0.80),  # min score of the group
+            'Python': pytest.approx(0.95),
+        }
+
+    def test_adjacent_begin_spans_stay_separate(self):
+        """Two B-tagged skills with only a space between them are NOT merged —
+        a 'B' always starts a fresh term."""
+        from apps.accounts.ner import jobbert
+
+        fake = MagicMock(return_value=[
+            {'entity_group': 'B', 'score': 0.9, 'word': 'Python',
+             'start': 0, 'end': 6},
+            {'entity_group': 'B', 'score': 0.85, 'word': 'SQL',
+             'start': 7, 'end': 10},
+        ])
+        with patch.object(jobbert, '_pipeline', fake):
+            out = jobbert.layer.predict("Python SQL")
+        assert out == {'Python': pytest.approx(0.9), 'SQL': pytest.approx(0.85)}
+
+    def test_gap_greater_than_one_keeps_tokens_separate(self):
+        """F-NER-FRAG boundary: a B token and a following I token separated by
+        more than one char (gap == 2) do NOT merge — pins the upper bound of
+        the continuation predicate (`0 <= start - cur_end <= 1`)."""
+        from apps.accounts.ner import jobbert
+
+        text = "machine  learning"  # two spaces → 2-char gap between the spans
+        fake = MagicMock(return_value=[
+            {'entity_group': 'B', 'score': 0.90, 'word': 'machine',
+             'start': 0, 'end': 7},
+            {'entity_group': 'I', 'score': 0.80, 'word': 'learning',
+             'start': 9, 'end': 17},  # gap == 2 → stays separate
+        ])
+        with patch.object(jobbert, '_pipeline', fake):
+            out = jobbert.layer.predict(text)
+        assert out == {
+            'machine': pytest.approx(0.90),
+            'learning': pytest.approx(0.80),
+        }
+
+    def test_bare_bio_prefixes_are_kept(self):
+        """Regression guard for the label-filter bug in jobbert.py.
+
+        The real jjzha/jobbert_skill_extraction model, under
+        aggregation_strategy="simple", emits entity_group as bare BIO
+        prefixes ("B" / "I") rather than the entity name. The old filter
+        (`"skill" not in label`) dropped every span. Since the model has
+        exactly one entity type (SKILL), every non-O span IS a skill.
+        """
+        from apps.accounts.ner import jobbert
+
+        fake = MagicMock(return_value=[
+            {'entity_group': 'B', 'score': 0.91, 'word': 'Python'},
+            {'entity_group': 'I', 'score': 0.76, 'word': 'Kubernetes'},
+            # Outside-span must still be dropped.
+            {'entity_group': 'O', 'score': 0.99, 'word': 'the'},
+        ])
+        with patch.object(jobbert, '_pipeline', fake):
+            out = jobbert.layer.predict("Python and Kubernetes the prod cluster")
+        assert out == {
+            'Python': pytest.approx(0.91),
+            'Kubernetes': pytest.approx(0.76),
+        }
+
+
+# ---------------------------------------------------------------------------
+# SBERT layer — DB-backed via SkillEmbedding + pgvector CosineDistance
+# ---------------------------------------------------------------------------
+class TestSbertLayer:
+    """Unit-level: we don't want to hit pgvector here. Stub the ORM path and
+    verify the layer's own logic (threshold + aggregation)."""
+
+    def test_below_threshold_is_dropped(self):
+        import numpy as np
+
+        from apps.accounts.ner import sbert
+
+        # Stub noun phrase extraction to avoid loading spacy.
+        with patch.object(sbert, '_candidate_phrases', return_value=['banana']):
+            fake_model = MagicMock()
+            # Real SentenceTransformer.encode returns a numpy ndarray; the
+            # layer calls .tolist() on it, so mirror the shape here.
+            fake_model.encode = MagicMock(return_value=np.array([[0.1] * 384]))
+            with patch.object(sbert, '_get_model', return_value=fake_model):
+                # pgvector query returns a match whose cosine distance is too
+                # high (similarity = 1 - 0.5 = 0.5 < 0.65 threshold).
+                fake_emb = MagicMock()
+                fake_emb.distance = 0.5
+                fake_emb.skill.skill_name = 'Python'
+                fake_qs = MagicMock()
+                fake_qs.annotate.return_value.order_by.return_value.select_related.return_value.first.return_value = fake_emb
+
+                with patch('apps.skills.models.SkillEmbedding.objects', fake_qs):
+                    out = sbert.layer.predict("I like banana smoothies")
+
+        assert out == {}  # below threshold → dropped
+
+
+# ---------------------------------------------------------------------------
+# Lexical floor — already covered by test_resume_parser.py; just confirm the
+# layer wrapper returns the expected shape.
+# ---------------------------------------------------------------------------
+@pytest.mark.django_db
+class TestLexicalLayer:
+    def test_wraps_existing_candidate_matches(self):
+        from apps.accounts.ner import lexical
+        from apps.skills.models import Skill
+
+        Skill.objects.create(skill_name='Python', category='Programming',
+                             difficulty_level='BEGINNER')
+        Skill.objects.create(skill_name='SQL', category='Database',
+                             difficulty_level='BEGINNER')
+
+        out = lexical.layer.predict("Strong Python and SQL background.")
+        assert set(out) == {'Python', 'SQL'}
+        assert all(0 < v <= 1.0 for v in out.values())

apps/accounts/tests/test_profile.py

@@ -0,0 +1,152 @@
+import pytest
+from rest_framework.test import APIClient
+from apps.skills.models import Skill
+
+pytestmark = pytest.mark.django_db
+
+REGISTER_URL = '/api/auth/register/'
+LOGIN_URL = '/api/auth/login/'
+PROFILE_URL = '/api/auth/profile/'
+PARSE_RESUME_URL = '/api/auth/profile/parse-resume/'
+SKILLS_URL = '/api/skills/'
+USER_SKILLS_URL = '/api/user-skills/'
+
+VALID_USER = {
+    'name': 'Test User',
+    'email': 'test2@example.com',
+    'password': 'TestPass123!',
+    'password_confirm': 'TestPass123!'
+}
+
+
+@pytest.fixture
+def api_client():
+    return APIClient()
+
+
+@pytest.fixture
+def skill(db):
+    return Skill.objects.create(
+        skill_name='Python',
+        category='Programming',
+        difficulty_level='BEGINNER'
+    )
+
+
+@pytest.fixture
+def auth_client(api_client):
+    api_client.post(REGISTER_URL, data=VALID_USER, format='json')
+    login_resp = api_client.post(
+        LOGIN_URL,
+        data={'email': VALID_USER['email'], 'password': VALID_USER['password']},
+        format='json'
+    )
+    token = login_resp.data['access']
+    api_client.credentials(HTTP_AUTHORIZATION=f'Bearer {token}')
+    return api_client
+
+
+class TestProfile:
+    def test_get_profile(self, auth_client):
+        """TC-05: GET /profile/ returns profile + skills."""
+        response = auth_client.get(PROFILE_URL)
+        assert response.status_code == 200
+        assert 'user' in response.data
+        assert 'profile' in response.data
+        assert 'skills' in response.data
+
+    def test_update_profile(self, auth_client):
+        """TC-05: PUT /profile/ updates degree, semester, bio."""
+        data = {
+            'degree': 'BS Computer Science',
+            'semester': 6,
+            'bio': 'I love coding',
+            'interests': 'AI, Web Dev'
+        }
+        response = auth_client.put(PROFILE_URL, data=data, format='json')
+        assert response.status_code == 200
+        assert response.data['profile']['degree'] == 'BS Computer Science'
+        assert response.data['profile']['semester'] == 6
+
+    def test_update_profile_with_skills(self, auth_client, skill):
+        """TC-06: PUT /profile/ with skills upserts UserSkills."""
+        data = {
+            'degree': 'BS CS',
+            'skills': [
+                {'skill_id': skill.id, 'proficiency': 65}
+            ]
+        }
+        response = auth_client.put(PROFILE_URL, data=data, format='json')
+        assert response.status_code == 200
+        skills = response.data['skills']
+        assert len(skills) == 1
+        assert skills[0]['proficiency'] == 65
+        assert skills[0]['user_level'] == 'ADVANCED'  # 65 > 60
+
+    def test_user_level_auto_computed(self, auth_client, skill):
+        """TC-06: user_level is auto-derived from proficiency."""
+        data = {'skills': [{'skill_id': skill.id, 'proficiency': 30}]}
+        response = auth_client.put(PROFILE_URL, data=data, format='json')
+        assert response.status_code == 200
+        assert response.data['skills'][0]['user_level'] == 'BEGINNER'  # 30 <= 40
+
+    def test_profile_requires_auth(self, api_client):
+        """Profile endpoints require authentication."""
+        response = api_client.get(PROFILE_URL)
+        assert response.status_code == 401
+
+
+class TestSkillCatalog:
+    def test_list_skills(self, auth_client, skill):
+        """GET /skills/ returns skill catalog (paginated)."""
+        response = auth_client.get(SKILLS_URL)
+        assert response.status_code == 200
+        assert response.data['count'] >= 1
+
+    def test_filter_by_category(self, auth_client, skill):
+        """GET /skills/?category=Programming filters skills."""
+        response = auth_client.get(f'{SKILLS_URL}?category=Programming')
+        assert response.status_code == 200
+        assert all(s['category'] == 'Programming' for s in response.data['results'])
+
+
+class TestUserSkills:
+    def test_add_user_skill(self, auth_client, skill):
+        """POST /user-skills/ adds a skill to user."""
+        data = {'skill_id': skill.id, 'proficiency': 50}
+        response = auth_client.post(USER_SKILLS_URL, data=data, format='json')
+        assert response.status_code == 201
+        assert response.data['proficiency'] == 50
+        assert response.data['user_level'] == 'INTERMEDIATE'
+
+    def test_update_user_skill(self, auth_client, skill):
+        """PUT /user-skills/<id>/ updates proficiency."""
+        # First add
+        add_resp = auth_client.post(
+            USER_SKILLS_URL, data={'skill_id': skill.id, 'proficiency': 30}, format='json'
+        )
+        skill_id = add_resp.data['id']
+        # Then update
+        update_resp = auth_client.put(
+            f'{USER_SKILLS_URL}{skill_id}/',
+            data={'skill_id': skill.id, 'proficiency': 70},
+            format='json'
+        )
+        assert update_resp.status_code == 200
+        assert update_resp.data['user_level'] == 'ADVANCED'
+
+
+class TestParseResumeStub:
+    """The Module 2 "stub" endpoint is now the real Module 8 MVP endpoint.
+    Kept under this class name for continuity — full happy-path + edge-case
+    coverage lives in apps/accounts/tests/test_resume_parser.py.
+    """
+
+    def test_requires_auth(self, api_client):
+        resp = api_client.post(PARSE_RESUME_URL, data={}, format='json')
+        assert resp.status_code == 401
+
+    def test_empty_body_returns_400(self, auth_client):
+        resp = auth_client.post(PARSE_RESUME_URL, data={}, format='multipart')
+        assert resp.status_code == 400
+        assert 'detail' in resp.data

apps/accounts/tests/test_resume_parser.py

@@ -0,0 +1,254 @@
+"""Module 8 MVP tests — lexical resume parser.
+
+Covers both the pure service function (extract_skills_from_pdf) and the HTTP
+endpoint that wraps it. PDFs are built in-memory with pdfplumber's underlying
+writer (reportlab isn't a dep, so we fake a minimal PDF byte stream via
+pdfminer). For robustness we also lean on pdfplumber itself to round-trip a
+known good fixture from pypdfium2's test payloads when possible — but the
+happy path here avoids extra deps.
+"""
+from __future__ import annotations
+
+import io
+
+import pytest
+from django.contrib.auth import get_user_model
+from rest_framework.test import APIClient
+
+from apps.accounts.resume_parser import (
+    ResumeParseError,
+    extract_skills_from_pdf,
+)
+from apps.skills.models import Skill
+
+
+User = get_user_model()
+pytestmark = pytest.mark.django_db
+
+
+# ---------------------------------------------------------------------------
+# PDF building — use pdfplumber's underlying pdfminer / pypdfium2 stack.
+# We render a minimal PDF with reportlab when available, else fall back to a
+# raw PDF byte stream crafted by hand. Both paths yield a PDF that pdfplumber
+# can extract_text() cleanly from.
+# ---------------------------------------------------------------------------
+def _build_pdf(text: str) -> bytes:
+    """Return a minimal valid single-page PDF containing `text`.
+
+    Uses pypdfium2 (which pdfplumber already depends on) to render text.
+    If rendering isn't available in this env we hand-craft a PDF — slower
+    to maintain but avoids adding a new dependency just for tests.
+    """
+    try:
+        # Preferred path: rely on a known-good PDF template from pypdfium2's
+        # bundled samples. If nothing ships, fall through to the hand-written
+        # variant.
+        import pypdfium2 as pdfium  # noqa: F401 — proves the dep is live
+    except Exception:
+        pass
+
+    # Hand-written minimal PDF — valid per the PDF 1.4 spec and parseable by
+    # pdfminer (pdfplumber's text extractor).
+    safe = text.replace("\\", "\\\\").replace("(", "\\(").replace(")", "\\)")
+    pdf = (
+        b"%PDF-1.4\n"
+        b"1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj\n"
+        b"2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj\n"
+        b"3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]"
+        b"/Contents 4 0 R/Resources<</Font<</F1 5 0 R>>>>>>endobj\n"
+    )
+    stream = (
+        "BT /F1 12 Tf 50 750 Td (" + safe + ") Tj ET"
+    ).encode("latin-1", errors="replace")
+    pdf += (
+        b"4 0 obj<</Length " + str(len(stream)).encode() + b">>stream\n" +
+        stream + b"\nendstream endobj\n"
+    )
+    pdf += (
+        b"5 0 obj<</Type/Font/Subtype/Type1/BaseFont/Helvetica>>endobj\n"
+        b"xref\n0 6\n"
+        b"0000000000 65535 f \n"
+    )
+    # xref entries — rough, but sufficient for pdfminer tolerant parsing.
+    pdf += b"0000000010 00000 n \n" * 5
+    pdf += (
+        b"trailer<</Size 6/Root 1 0 R>>\n"
+        b"startxref\n"
+        b"0\n"
+        b"%%EOF\n"
+    )
+    return pdf
+
+
+@pytest.fixture
+def catalog():
+    py = Skill.objects.create(
+        skill_name='Python', category='Programming', difficulty_level='BEGINNER')
+    sql = Skill.objects.create(
+        skill_name='SQL', category='Database', difficulty_level='BEGINNER')
+    ml = Skill.objects.create(
+        skill_name='Machine Learning', category='AI',
+        difficulty_level='INTERMEDIATE')
+    react = Skill.objects.create(
+        skill_name='React', category='Frontend', difficulty_level='INTERMEDIATE')
+    return {'python': py, 'sql': sql, 'ml': ml, 'react': react}
+
+
+# ---------------------------------------------------------------------------
+# Pure service tests
+# ---------------------------------------------------------------------------
+class TestExtractSkillsFromPdf:
+    def test_empty_bytes_raises(self, catalog):
+        with pytest.raises(ResumeParseError):
+            extract_skills_from_pdf(b"")
+
+    def test_oversized_raises(self, catalog):
+        with pytest.raises(ResumeParseError):
+            extract_skills_from_pdf(b"x" * (6 * 1024 * 1024))
+
+    def test_corrupt_pdf_raises_user_error(self, catalog):
+        with pytest.raises(ResumeParseError):
+            extract_skills_from_pdf(b"not a pdf at all")
+
+    def test_exact_skill_names_extracted(self, catalog):
+        pdf = _build_pdf(
+            "Experienced developer with Python, SQL and React expertise. "
+            "5 years of Machine Learning experience."
+        )
+        predictions = extract_skills_from_pdf(pdf)
+        names = {p['skill_name'] for p in predictions}
+        # At least the catalog skills we planted should show up.
+        assert {'Python', 'SQL', 'Machine Learning', 'React'} <= names
+
+    def test_experience_markers_boost_proficiency(self, catalog):
+        pdf = _build_pdf(
+            "Expert Python developer with 8 years of experience. Basic SQL."
+        )
+        predictions = extract_skills_from_pdf(pdf)
+        by_name = {p['skill_name']: p for p in predictions}
+        # Python context has "Expert" + "years" → top bucket
+        # SQL context has "Basic" → mid-low bucket
+        assert by_name['Python']['proficiency'] >= by_name['SQL']['proficiency']
+
+    def test_results_sorted_by_confidence_desc(self, catalog):
+        pdf = _build_pdf("Python SQL React Machine Learning")
+        predictions = extract_skills_from_pdf(pdf)
+        confidences = [p['confidence'] for p in predictions]
+        assert confidences == sorted(confidences, reverse=True)
+
+    def test_unknown_skills_not_created(self, catalog):
+        before = Skill.objects.count()
+        pdf = _build_pdf(
+            "Brainfuck and Whitespace and Malbolge are my specialties."
+        )
+        _ = extract_skills_from_pdf(pdf)
+        assert Skill.objects.count() == before
+
+    def test_no_matches_returns_empty_list(self, catalog):
+        pdf = _build_pdf("I love woodworking and baking sourdough bread.")
+        predictions = extract_skills_from_pdf(pdf)
+        # "bread" might false-positive via fuzzy on short names, so only
+        # assert there's no catalog name returned.
+        names = {p['skill_name'] for p in predictions}
+        assert names.isdisjoint({'Python', 'SQL', 'React', 'Machine Learning'})
+
+    def test_predictions_carry_matched_span_for_exact_hits(self, catalog):
+        pdf = _build_pdf(
+            "Built ML pipelines. Strong Python and React background."
+        )
+        predictions = extract_skills_from_pdf(pdf)
+        py = next(p for p in predictions if p['skill_name'] == 'Python')
+        assert 'python' in py['matched_span'].lower()
+
+    def test_proficiency_aggregates_across_windows(self, catalog):
+        """When a skill appears multiple times with conflicting signals, the
+        strongest claim wins — not the first occurrence.
+
+        Here Python appears twice: first as "beginner Python" (NOVICE=40) then
+        as "lead Python team" (STRONG=70). Under the pre-#11 single-window
+        logic the first match won → proficiency 40. With multi-window
+        aggregation the STRONG signal should prevail → proficiency 70.
+        """
+        pdf = _build_pdf(
+            "Learning path started as a beginner Python student. "
+            "Now lead Python team of five engineers building data platforms."
+        )
+        predictions = extract_skills_from_pdf(pdf)
+        py = next(p for p in predictions if p['skill_name'] == 'Python')
+        assert py['proficiency'] == 70
+
+
+# ---------------------------------------------------------------------------
+# HTTP endpoint tests
+# ---------------------------------------------------------------------------
+def _auth_client():
+    user = User.objects.create_user(
+        username='parser@x.com', email='parser@x.com',
+        password='StrongPass123!', name='Parser',
+    )
+    c = APIClient()
+    c.force_authenticate(user=user)
+    return c
+
+
+class TestParseResumeEndpoint:
+    URL = '/api/auth/profile/parse-resume/'
+
+    def test_requires_authentication(self):
+        c = APIClient()
+        r = c.post(self.URL, data={}, format='multipart')
+        assert r.status_code == 401
+
+    def test_empty_body_returns_400(self, catalog):
+        c = _auth_client()
+        r = c.post(self.URL, data={}, format='multipart')
+        assert r.status_code == 400
+        assert 'resume' in r.data['detail'].lower() or \
+            'pdf' in r.data['detail'].lower()
+
+    def test_empty_file_returns_400(self, catalog):
+        c = _auth_client()
+        upload = io.BytesIO(b"")
+        upload.name = 'empty.pdf'
+        r = c.post(self.URL, data={'resume': upload}, format='multipart')
+        assert r.status_code == 400
+
+    def test_corrupt_pdf_returns_400(self, catalog):
+        c = _auth_client()
+        upload = io.BytesIO(b"not a pdf")
+        upload.name = 'garbage.pdf'
+        r = c.post(self.URL, data={'resume': upload}, format='multipart')
+        assert r.status_code == 400
+
+    def test_happy_path_returns_skills(self, catalog):
+        c = _auth_client()
+        upload = io.BytesIO(_build_pdf(
+            "Senior Python developer. Deep Machine Learning background. "
+            "React on the frontend. 7 years experience."
+        ))
+        upload.name = 'resume.pdf'
+        r = c.post(self.URL, data={'resume': upload}, format='multipart')
+        assert r.status_code == 200
+        body = r.data
+        assert 'skills' in body
+        # parser_version is now a list of layer names (e.g. ['lexical']).
+        # Under the CI pin GAPGUIDE_PARSE_LAYERS=lexical the floor is the
+        # only layer firing.
+        assert isinstance(body['parser_version'], list)
+        assert 'lexical' in body['parser_version']
+        names = {s['skill_name'] for s in body['skills']}
+        # At least Python and React should land — those are unambiguous.
+        assert 'Python' in names
+        assert 'React' in names
+
+    def test_no_state_mutation(self, catalog):
+        """Parsing is read-only — must not create UserSkill or Skill rows."""
+        from apps.skills.models import UserSkill
+        c = _auth_client()
+        skill_count = Skill.objects.count()
+        us_count = UserSkill.objects.count()
+        upload = io.BytesIO(_build_pdf("Python Java React"))
+        upload.name = 'resume.pdf'
+        c.post(self.URL, data={'resume': upload}, format='multipart')
+        assert Skill.objects.count() == skill_count
+        assert UserSkill.objects.count() == us_count

apps/accounts/tests/test_resume_parser_integration.py

@@ -0,0 +1,102 @@
+"""End-to-end NER chain integration test.
+
+Gated on ``GAPGUIDE_ML_SMOKE=1`` — runs the REAL four-layer chain
+(Nucha + JobBERT + SkillNER + SBERT + lexical) against a fixture PDF. CI
+sets GAPGUIDE_PARSE_LAYERS=lexical (see conftest.py), so this opt-in test
+is the only place we verify the ML stack actually works end-to-end.
+
+Run manually:
+    $env:GAPGUIDE_ML_SMOKE="1"
+    pytest apps/accounts/tests/test_resume_parser_integration.py -q
+
+First run downloads ~1 GB of HF models + requires `en_core_web_lg`
+installed and pgvector extension in Postgres with SkillEmbedding populated.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+
+pytestmark = [
+    pytest.mark.django_db(transaction=True),
+    pytest.mark.skipif(
+        os.environ.get("GAPGUIDE_ML_SMOKE") != "1",
+        reason="ML smoke disabled (set GAPGUIDE_ML_SMOKE=1 to enable)",
+    ),
+]
+
+
+FIX = Path(__file__).resolve().parent.parent.parent.parent / 'tests' / 'fixtures' / 'resumes'
+
+
+@pytest.fixture
+def seeded_catalog():
+    """Real catalog + SBERT embeddings. Requires:
+      * pgvector extension on the test DB
+      * en_core_web_lg installed
+      * seed_initial_skills has been run (we do it here)
+    """
+    from django.core.management import call_command
+    call_command('seed_initial_skills')
+
+    # Build embeddings for the seeded skills.
+    from apps.skills.models import Skill, SkillEmbedding
+    from sentence_transformers import SentenceTransformer
+    model = SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')
+    skills = list(Skill.objects.all())
+    vectors = model.encode(
+        [f"{s.skill_name} — {s.description or s.category}" for s in skills],
+        normalize_embeddings=True,
+    )
+    for skill, vec in zip(skills, vectors):
+        SkillEmbedding.objects.update_or_create(
+            skill=skill,
+            defaults={
+                'embedding': vec.tolist(),
+                'source_text': skill.skill_name,
+            },
+        )
+    return skills
+
+
+def test_full_chain_extracts_core_skills_from_strong_fixture(seeded_catalog):
+    """resume_ds_strong.pdf must yield at least {Python, SQL} via the full chain.
+
+    We deliberately don't assert exact counts / confidences — those depend
+    on the specific HF model versions and would flake across upgrades.
+    """
+    # Force the full chain.
+    os.environ.pop('GAPGUIDE_PARSE_LAYERS', None)
+    from apps.accounts.resume_parser import parse_resume_envelope
+
+    pdf = (FIX / 'resume_ds_strong.pdf').read_bytes()
+    env = parse_resume_envelope(pdf)
+
+    names = {s['skill_name'] for s in env['skills']}
+    assert {'Python', 'SQL'}.issubset(names), (env['parser_version'], names)
+
+    # At least one BERT/SBERT/SkillNER layer must have fired — proves the
+    # chain isn't silently falling back to lexical-only.
+    assert any(
+        layer in env['parser_version']
+        for layer in ('nucha', 'jobbert', 'skillner', 'sbert')
+    ), env['parser_version']
+
+
+def test_minimal_fixture_exercises_sbert_fallback(seeded_catalog):
+    """resume_minimal.pdf uses paraphrased skills ("data visualisation",
+    "version control"). Lexical layer alone returns nothing; the SBERT
+    fallback should resolve at least one paraphrase to a catalog skill.
+    """
+    os.environ.pop('GAPGUIDE_PARSE_LAYERS', None)
+    from apps.accounts.resume_parser import parse_resume_envelope
+
+    pdf = (FIX / 'resume_minimal.pdf').read_bytes()
+    env = parse_resume_envelope(pdf)
+
+    # Either SBERT or SkillNER should salvage at least one catalog hit here —
+    # otherwise the fallback chain isn't doing the job it was designed for.
+    assert len(env['skills']) >= 1, (env['parser_version'], env['skills'])

apps/accounts/urls.py

@@ -0,0 +1,16 @@
+from django.urls import path
+from rest_framework_simplejwt.views import TokenRefreshView
+from .views import (
+    RegisterView, LoginView, LogoutView, UserMeView,
+    ProfileView, ParseResumeStubView,
+)
+
+urlpatterns = [
+    path('register/', RegisterView.as_view(), name='register'),
+    path('login/', LoginView.as_view(), name='login'),
+    path('logout/', LogoutView.as_view(), name='logout'),
+    path('me/', UserMeView.as_view(), name='user-me'),
+    path('token/refresh/', TokenRefreshView.as_view(), name='token-refresh'),
+    path('profile/', ProfileView.as_view(), name='profile'),
+    path('profile/parse-resume/', ParseResumeStubView.as_view(), name='profile-parse-resume'),
+]

apps/accounts/views.py

@@ -0,0 +1,293 @@
+from drf_spectacular.types import OpenApiTypes
+from drf_spectacular.utils import OpenApiResponse, extend_schema, inline_serializer
+from rest_framework import generics, permissions, serializers, status
+from rest_framework.exceptions import ValidationError
+from rest_framework.response import Response
+from rest_framework.throttling import ScopedRateThrottle
+from rest_framework.views import APIView
+from rest_framework_simplejwt.exceptions import TokenError
+from rest_framework_simplejwt.tokens import RefreshToken
+from django.contrib.auth import get_user_model
+from django.db import transaction, IntegrityError
+
+from apps.skills.models import Skill, UserSkill
+from apps.skills.utils import proficiency_to_level
+
+from .models import UserProfile
+from .serializers import (
+    LoginSerializer,
+    ProfileWithSkillsSerializer,
+    RegisterSerializer,
+    UserProfileSerializer,
+    UserSerializer,
+)
+
+User = get_user_model()
+
+
+# Shape for endpoints that issue JWTs (register, login).
+_AUTH_RESPONSE = inline_serializer(
+    name='AuthTokenResponse',
+    fields={
+        'access': serializers.CharField(),
+        'refresh': serializers.CharField(),
+        'user': UserSerializer(),
+    },
+)
+
+
+@extend_schema(
+    responses={
+        201: _AUTH_RESPONSE,
+        400: OpenApiResponse(
+            description='Validation error — duplicate email, weak/mismatched '
+            'password, or missing fields (body is {"<field>": [...]}).',
+        ),
+    },
+)
+class RegisterView(generics.CreateAPIView):
+    queryset = User.objects.all()
+    permission_classes = [permissions.AllowAny]
+    throttle_classes = [ScopedRateThrottle]
+    throttle_scope = 'register'
+    serializer_class = RegisterSerializer
+
+    def create(self, request, *args, **kwargs):
+        serializer = self.get_serializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        try:
+            user = serializer.save()
+        except IntegrityError:
+            # Concurrent-registration race: two simultaneous case-variant emails
+            # can both pass the case-insensitive validate_email check; both then
+            # insert the SAME app-lowercased value, and the plain `unique=True`
+            # constraint on email/username rejects the loser. Surface a clean 400
+            # keyed on `email` (matching validate_email) instead of a 500.
+            return Response(
+                {'email': ['A user with this email already exists.']},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        refresh = RefreshToken.for_user(user)
+        return Response({
+            'access': str(refresh.access_token),
+            'refresh': str(refresh),
+            'user': UserSerializer(user).data
+        }, status=status.HTTP_201_CREATED)
+
+
+@extend_schema(
+    request=LoginSerializer,
+    responses={200: _AUTH_RESPONSE},
+)
+class LoginView(APIView):
+    serializer_class = LoginSerializer
+    permission_classes = [permissions.AllowAny]
+    throttle_classes = [ScopedRateThrottle]
+    throttle_scope = 'login'
+
+    def post(self, request):
+        serializer = LoginSerializer(data=request.data, context={'request': request})
+        serializer.is_valid(raise_exception=True)
+        user = serializer.validated_data
+
+        refresh = RefreshToken.for_user(user)
+
+        return Response({
+            'access': str(refresh.access_token),
+            'refresh': str(refresh),
+            'user': UserSerializer(user).data
+        }, status=status.HTTP_200_OK)
+
+
+@extend_schema(
+    request=inline_serializer(
+        name='LogoutRequest',
+        fields={'refresh_token': serializers.CharField()},
+    ),
+    responses={
+        204: OpenApiResponse(description='Token blacklisted.'),
+        400: OpenApiResponse(description='Missing or invalid refresh token.'),
+    },
+)
+class LogoutView(APIView):
+    permission_classes = [permissions.IsAuthenticated]
+
+    def post(self, request):
+        try:
+            refresh_token = request.data.get('refresh_token')
+            if not refresh_token:
+                return Response(
+                    {'detail': 'refresh_token is required'},
+                    status=status.HTTP_400_BAD_REQUEST
+                )
+            token = RefreshToken(refresh_token)
+            token.blacklist()
+            return Response(status=status.HTTP_204_NO_CONTENT)
+        except TokenError:
+            return Response(
+                {'detail': 'Invalid or expired token'},
+                status=status.HTTP_400_BAD_REQUEST
+            )
+
+
+class UserMeView(generics.RetrieveAPIView):
+    serializer_class = UserSerializer
+    permission_classes = [permissions.IsAuthenticated]
+
+    def get_object(self):
+        return self.request.user
+
+
+@extend_schema(
+    request={
+        'multipart/form-data': inline_serializer(
+            name='ResumeUpload',
+            fields={'resume': serializers.FileField()},
+        ),
+    },
+    responses={
+        200: inline_serializer(
+            name='ParseResumeResponse',
+            fields={
+                'skills': serializers.ListField(child=serializers.DictField()),
+                'parser_version': serializers.ListField(child=serializers.CharField()),
+                'note': serializers.CharField(),
+            },
+        ),
+        400: OpenApiResponse(description='Empty / missing file or parse error.'),
+    },
+)
+class ParseResumeStubView(APIView):
+    """Resume parsing — Module 8 MVP.
+
+    Accepts a multipart PDF upload and returns pre-fill predictions scored
+    against the Skill catalog. This is the "degraded fallback" layer in the
+    research/06-dataset-sourcing.md §5 fallback chain — pdfplumber + lexical
+    match. Higher NER layers can be plugged in behind
+    `apps.accounts.resume_parser.extract_skills_from_pdf` when the ML
+    env-setup track (SpaCy/BERT wheels + pgvector) lands.
+
+    Class name kept as-is (`ParseResumeStubView`) so URLConf + existing routes
+    don't churn — the view is no longer a stub but the URL name is stable.
+    """
+    permission_classes = [permissions.IsAuthenticated]
+    throttle_classes = [ScopedRateThrottle]
+    throttle_scope = 'resume_parse'
+
+    def post(self, request):
+        upload = (
+            request.FILES.get('resume')
+            or request.FILES.get('file')
+            or next(iter(request.FILES.values()), None)
+        )
+        if upload is None:
+            return Response(
+                {"detail": "Upload a PDF file under the 'resume' form field."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        if upload.size == 0:
+            return Response(
+                {"detail": "Uploaded file is empty."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        from .resume_parser import ResumeParseError, parse_resume_envelope
+
+        try:
+            envelope = parse_resume_envelope(upload.read())
+        except ResumeParseError as exc:
+            return Response(
+                {"detail": str(exc)},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        return Response(
+            {
+                "skills": envelope["skills"],
+                "parser_version": envelope["parser_version"],
+                "note": (
+                    "Predictions are merged across the layers listed above. "
+                    "Review the proficiency values — they are heuristics from "
+                    "the surrounding context, not assertions."
+                ),
+            },
+            status=status.HTTP_200_OK,
+        )
+
+
+class ProfileView(APIView):
+    serializer_class = ProfileWithSkillsSerializer
+    permission_classes = [permissions.IsAuthenticated]
+
+    @extend_schema(responses=ProfileWithSkillsSerializer)
+    def get(self, request):
+        user = request.user
+        UserProfile.objects.get_or_create(user=user)
+        serializer = ProfileWithSkillsSerializer(user)
+        return Response(serializer.data, status=status.HTTP_200_OK)
+
+    @extend_schema(
+        request=inline_serializer(
+            name='ProfileUpdateRequest',
+            fields={
+                'degree': serializers.CharField(required=False, allow_blank=True),
+                'semester': serializers.IntegerField(required=False, allow_null=True),
+                'interests': serializers.CharField(required=False, allow_blank=True),
+                'bio': serializers.CharField(required=False, allow_blank=True),
+                'skills': serializers.ListField(
+                    child=inline_serializer(
+                        name='ProfileSkillItem',
+                        fields={
+                            'skill_id': serializers.IntegerField(),
+                            'proficiency': serializers.IntegerField(min_value=0, max_value=100),
+                        },
+                    ),
+                    required=False,
+                ),
+            },
+        ),
+        responses=ProfileWithSkillsSerializer,
+    )
+    @transaction.atomic
+    def put(self, request):
+        user = request.user
+        profile, _ = UserProfile.objects.get_or_create(user=user)
+
+        profile_serializer = UserProfileSerializer(
+            profile, data=request.data, partial=True
+        )
+        profile_serializer.is_valid(raise_exception=True)
+        profile_serializer.save()
+
+        # Upsert skills (transactional — any error rolls back all changes)
+        skills_data = request.data.get('skills', []) or []
+        requested_ids = {
+            int(item['skill_id']) for item in skills_data
+            if item.get('skill_id') is not None and item.get('proficiency') is not None
+        }
+        known_ids = set(
+            Skill.objects.filter(id__in=requested_ids).values_list('id', flat=True)
+        ) if requested_ids else set()
+
+        for item in skills_data:
+            skill_id = item.get('skill_id')
+            proficiency = item.get('proficiency')
+            if skill_id is None or proficiency is None:
+                continue
+            skill_id = int(skill_id)
+            proficiency = int(proficiency)
+            if not (0 <= proficiency <= 100):
+                raise ValidationError(f"Proficiency must be 0-100 for skill_id {skill_id}")
+            if skill_id not in known_ids:
+                raise ValidationError(f"Skill with id={skill_id} does not exist")
+            UserSkill.objects.update_or_create(
+                user=user, skill_id=skill_id,
+                defaults={
+                    'proficiency': proficiency,
+                    'user_level': proficiency_to_level(proficiency)
+                }
+            )
+
+        serializer = ProfileWithSkillsSerializer(user)
+        return Response(serializer.data, status=status.HTTP_200_OK)

apps/analysis/admin.py

@@ -0,0 +1 @@
+from django.contrib import admin

apps/analysis/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class AnalysisConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'apps.analysis'

apps/analysis/models.py

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

apps/analysis/services.py

@@ -0,0 +1,479 @@
+"""Gap Analysis + Recommendation services.
+
+Gap analysis — Weighted Competency Fulfillment Algorithm.
+See research/design-decision-changes.md §Module 4 for derivation. Pure functions,
+no DB writes: the report is computed on demand from UserSkill + RoleSkill state.
+
+Recommendations — composite ranking over the Resource catalog.
+See research/08-next-modules-build-plan.md §Module A. Type weights from
+research/03-gap-analysis-engine-research.md §2.1 are the single source of truth
+for type preference.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Iterable
+
+from apps.resources.models import Resource, SkillResource
+from apps.roles.models import Role, RoleSkill
+from apps.skills.models import UserSkill
+from apps.skills.utils import proficiency_to_level
+
+
+LEVEL_THRESHOLDS: dict[str, int] = {
+    'BEGINNER': 40,
+    'INTERMEDIATE': 60,
+    'ADVANCED': 100,
+}
+
+MANDATORY_CAP = 60.0
+
+BANDS: list[tuple[float, str]] = [
+    (85.0, 'STRONG'),
+    (65.0, 'GOOD'),
+    (45.0, 'PARTIAL'),
+    (0.0, 'WEAK'),
+]
+
+
+@dataclass
+class SkillGap:
+    skill_id: int
+    skill_name: str
+    category: str
+    required_level: str
+    threshold: int
+    user_proficiency: int
+    weight: float
+    is_mandatory: bool
+    gap: int
+    satisfaction: float
+    gap_type: str
+    severity: str | None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class GapReport:
+    role_id: int
+    role_name: str
+    readiness: float
+    band: str
+    mandatory_cap_applied: bool
+    no_requirements: bool
+    gaps: list[SkillGap] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            'role_id': self.role_id,
+            'role_name': self.role_name,
+            'readiness': round(self.readiness, 2),
+            'band': self.band,
+            'mandatory_cap_applied': self.mandatory_cap_applied,
+            'mandatory_cap': MANDATORY_CAP,
+            'no_requirements': self.no_requirements,
+            'gaps': [g.to_dict() for g in self.gaps],
+        }
+
+
+def _band_for(readiness: float) -> str:
+    for floor, name in BANDS:
+        if readiness >= floor:
+            return name
+    return 'WEAK'
+
+
+def _classify(
+    user_proficiency: int,
+    threshold: int,
+    is_mandatory: bool,
+) -> tuple[str, str | None]:
+    """Return (gap_type, severity) per §3 of design-decision-changes.md."""
+    if user_proficiency >= threshold:
+        return 'MET', None
+
+    if user_proficiency == 0:
+        return 'MISSING', 'CRITICAL' if is_mandatory else 'MEDIUM'
+
+    ratio = (threshold - user_proficiency) / threshold
+    if is_mandatory or ratio >= 0.5:
+        severity = 'HIGH'
+    elif ratio >= 0.25:
+        severity = 'MEDIUM'
+    else:
+        severity = 'LOW'
+    return 'INSUFFICIENT', severity
+
+
+def _user_proficiency_map(user_id: int, skill_ids: Iterable[int]) -> dict[int, int]:
+    qs = UserSkill.objects.filter(user_id=user_id, skill_id__in=list(skill_ids))
+    return {us.skill_id: us.proficiency for us in qs}
+
+
+def compute_gap_report(user, role: Role) -> GapReport:
+    role_skills = list(
+        RoleSkill.objects.filter(role=role).select_related('skill')
+    )
+
+    if not role_skills:
+        return GapReport(
+            role_id=role.id,
+            role_name=role.role_name,
+            readiness=100.0,
+            band=_band_for(100.0),
+            mandatory_cap_applied=False,
+            no_requirements=True,
+        )
+
+    prof_map = _user_proficiency_map(user.id, (rs.skill_id for rs in role_skills))
+
+    gaps: list[SkillGap] = []
+    weighted_sat_sum = 0.0
+    weight_sum = 0.0
+    mandatory_shortfall = False
+
+    for rs in role_skills:
+        threshold = LEVEL_THRESHOLDS[rs.required_level]
+        user_prof = prof_map.get(rs.skill_id, 0)
+        satisfaction = min(user_prof / threshold, 1.0)
+        gap_points = max(threshold - user_prof, 0)
+        gap_type, severity = _classify(user_prof, threshold, rs.is_mandatory)
+
+        if rs.is_mandatory and satisfaction < 1.0:
+            mandatory_shortfall = True
+
+        weight_sum += rs.weight
+        weighted_sat_sum += satisfaction * rs.weight
+
+        gaps.append(SkillGap(
+            skill_id=rs.skill_id,
+            skill_name=rs.skill.skill_name,
+            category=rs.skill.category,
+            required_level=rs.required_level,
+            threshold=threshold,
+            user_proficiency=user_prof,
+            weight=rs.weight,
+            is_mandatory=rs.is_mandatory,
+            gap=gap_points,
+            satisfaction=round(satisfaction, 4),
+            gap_type=gap_type,
+            severity=severity,
+        ))
+
+    if weight_sum <= 0:
+        # No positive weight to aggregate. With the RoleSkill DB CheckConstraints
+        # in force a mandatory skill always has weight>0, so weight_sum<=0 implies
+        # no mandatory shortfall and the documented zero-weight contract returns
+        # 100/no_requirements. The mandatory branch is defense-in-depth against a
+        # constraint-bypassing bulk write — it avoids a 0.0/0.0 ZeroDivisionError.
+        readiness = 0.0 if mandatory_shortfall else 100.0
+        return GapReport(
+            role_id=role.id,
+            role_name=role.role_name,
+            readiness=readiness,
+            band=_band_for(readiness),
+            # readiness here is 0 (mandatory unmet) or 100 (no requirements);
+            # neither is a value "capped down to 60", so the cap is not applied.
+            mandatory_cap_applied=False,
+            no_requirements=not mandatory_shortfall,
+            gaps=gaps,
+        )
+
+    raw_readiness = (weighted_sat_sum / weight_sum) * 100.0
+    cap_applied = mandatory_shortfall and raw_readiness > MANDATORY_CAP
+    readiness = MANDATORY_CAP if cap_applied else raw_readiness
+    readiness = max(0.0, min(readiness, 100.0))
+
+    gaps.sort(
+        key=lambda g: (
+            -{'CRITICAL': 4, 'HIGH': 3, 'MEDIUM': 2, 'LOW': 1, None: 0}[g.severity],
+            -g.weight,
+            g.skill_name,
+        )
+    )
+
+    return GapReport(
+        role_id=role.id,
+        role_name=role.role_name,
+        readiness=readiness,
+        band=_band_for(readiness),
+        mandatory_cap_applied=cap_applied,
+        no_requirements=False,
+        gaps=gaps,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Recommendation service
+# ---------------------------------------------------------------------------
+#
+# Recommendations are ranked by a TWO-KEYED order so that material which is
+# clearly the wrong level can never leapfrog appropriately-levelled material on
+# quality (type/relevance/rating) alone:
+#
+#   1. LEVEL TIER (primary) — the distance between the user's CURRENT level for
+#      the skill (proficiency_to_level(), NOT the role's required level) and the
+#      resource's difficulty. distance 0-1 = "near" (tier 0); distance >=2 =
+#      "far" (tier 1). Every near resource ranks above every far one. So a
+#      beginner always sees BEGINNER/INTERMEDIATE content before ADVANCED — a
+#      hard guarantee, independent of how good the far resource looks otherwise.
+#
+#   2. COMPOSITE QUALITY SCORE (secondary) — orders resources WITHIN a tier:
+#
+#        score = TYPE_WEIGHT[type] * w_type
+#              + DIFFICULTY_MATCH(user_current_level, difficulty) * w_diff
+#              + relevance_score * 10 * w_rel          # normalise to 0..10
+#              + (rating / 5.0) * 10 * w_rating        # normalise to 0..10
+#
+#      Within the near tier the difficulty term still gives exact-level a gentle
+#      edge over one-level-off, but it stays SOFT: a much more relevant/stronger
+#      one-level-off resource can still outrank a weak exact-level one. The only
+#      HARD rule is the near-over-far split above.
+#
+# Coefficients (single source of truth — keep in sync with the docstring above):
+#
+#   w_type    = 1.0   (dominant — follows the type preference from research
+#                      §2.1 "Video > Course > Article > Docs")
+#   w_diff    = 1.0
+#   w_rel     = 1.5   (relevance is heavily weighted — a very-relevant DOCS
+#                      can outrank a somewhat-relevant VIDEO at the same level)
+#   w_rating  = 0.5
+#
+# Notable consequences, verified by unit tests:
+#   * Equal rating/relevance/difficulty → VIDEO > COURSE > ARTICLE > DOCS.
+#   * A resource <=1 level from the user ALWAYS ranks above one >=2 levels away,
+#     regardless of type/relevance/rating (the level-tier guarantee).
+#   * Within a tier, exact-level beats one-level-off on equal quality, yet a
+#     relevance_score=1.0 DOCS can outrank a relevance_score=0.3 VIDEO at the
+#     same level (relevance is weighted 1.5x), both at rating 3.5/5:
+#       DOCS : 4*1.0 + 10*1.0 + (1.0*10)*1.5 + (3.5/5*10)*0.5 = 32.5
+#       VIDEO: 10*1.0 + 10*1.0 + (0.3*10)*1.5 + (3.5/5*10)*0.5 = 28.0
+#   * Stable tie-break by resource_id ASC so API snapshots don't flap.
+
+TYPE_WEIGHTS: dict[str, int] = {
+    'VIDEO': 10,
+    'COURSE': 8,
+    'ARTICLE': 6,
+    'DOCS': 4,
+}
+
+DIFFICULTY_ORDER: dict[str, int] = {
+    'BEGINNER': 0,
+    'INTERMEDIATE': 1,
+    'ADVANCED': 2,
+}
+
+W_TYPE = 1.0
+W_DIFF = 1.0
+W_REL = 1.5
+W_RATING = 0.5
+
+DIFFICULTY_EXACT = 10.0
+DIFFICULTY_ADJACENT = 5.0
+DIFFICULTY_MISMATCH = 0.0
+
+# A resource within this many levels of the user's current level is "near"
+# (tier 0); anything further is "far" (tier 1) and is ranked below every near
+# resource. With the 3-level scale this means: appropriate-level + one step are
+# near, a two-step mismatch (e.g. ADVANCED for a BEGINNER) is far.
+NEAR_MAX_DISTANCE = 1
+
+DEFAULT_LIMIT_PER_SKILL = 3
+
+# Upper bound on resources returned per skill gap. Caps an adversarial
+# ?limit=99999999 so a single request can't try to materialise the whole
+# catalog per skill; the curated catalog is small, so 50 is generous.
+MAX_LIMIT_PER_SKILL = 50
+
+
+@dataclass
+class RecommendationItem:
+    resource_id: int
+    title: str
+    provider: str
+    url: str
+    type: str
+    difficulty_level: str
+    duration: int
+    rating: float
+    relevance_score: float
+    score: float
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def _difficulty_match_score(anchor_level: str, resource_level: str) -> float:
+    anchor = DIFFICULTY_ORDER[anchor_level]
+    res = DIFFICULTY_ORDER[resource_level]
+    dist = abs(anchor - res)
+    if dist == 0:
+        return DIFFICULTY_EXACT
+    if dist == 1:
+        return DIFFICULTY_ADJACENT
+    return DIFFICULTY_MISMATCH
+
+
+def _difficulty_tier(anchor_level: str, resource_level: str) -> int:
+    """Primary ranking key: 0 if the resource is within NEAR_MAX_DISTANCE levels
+    of the user's current level ("near"), else 1 ("far").
+
+    Sorting on this BEFORE the composite score guarantees a clearly-mismatched
+    resource (>=2 levels off, e.g. ADVANCED for a beginner) can never outrank an
+    appropriately-levelled one on type/relevance/rating alone.
+    """
+    dist = abs(DIFFICULTY_ORDER[anchor_level] - DIFFICULTY_ORDER[resource_level])
+    return 0 if dist <= NEAR_MAX_DISTANCE else 1
+
+
+def _score(
+    type_: str,
+    anchor_level: str,
+    resource_level: str,
+    relevance_score: float,
+    rating: float,
+) -> float:
+    return (
+        TYPE_WEIGHTS.get(type_, 0) * W_TYPE
+        + _difficulty_match_score(anchor_level, resource_level) * W_DIFF
+        + (relevance_score * 10.0) * W_REL
+        + (rating / 5.0 * 10.0) * W_RATING
+    )
+
+
+def compute_recommendations(
+    user,
+    role: Role,
+    limit_per_skill: int = DEFAULT_LIMIT_PER_SKILL,
+) -> dict:
+    """Return {"role_id", "role_name", "recommendations": {skill_id: [...]}}.
+
+    Only returns entries for skills with an actual gap (MISSING or INSUFFICIENT);
+    MET skills are skipped. Stable tie-break by resource_id ASC.
+    """
+    report = compute_gap_report(user, role)
+
+    gap_skills = [g for g in report.gaps if g.gap_type != 'MET']
+
+    recommendations: dict[int, list[dict]] = {}
+    if not gap_skills:
+        return {
+            'role_id': role.id,
+            'role_name': role.role_name,
+            'recommendations': recommendations,
+        }
+
+    skill_ids = [g.skill_id for g in gap_skills]
+    links = (
+        SkillResource.objects
+        .filter(skill_id__in=skill_ids)
+        .select_related('resource')
+    )
+
+    by_skill: dict[int, list[tuple[SkillResource, Resource]]] = {
+        sid: [] for sid in skill_ids
+    }
+    for link in links:
+        by_skill[link.skill_id].append((link, link.resource))
+
+    # Anchor difficulty matching to the user's CURRENT level for each gap skill
+    # (derived from proficiency), not the role's required level — so learners are
+    # steered to material at their level first. See the scoring block above.
+    anchor_by_skill = {
+        g.skill_id: proficiency_to_level(g.user_proficiency) for g in gap_skills
+    }
+
+    for skill_id, pairs in by_skill.items():
+        anchor_level = anchor_by_skill[skill_id]
+        scored: list[tuple[int, float, int, RecommendationItem]] = []
+        for link, resource in pairs:
+            score = _score(
+                resource.type,
+                anchor_level,
+                resource.difficulty_level,
+                link.relevance_score,
+                resource.rating,
+            )
+            tier = _difficulty_tier(anchor_level, resource.difficulty_level)
+            scored.append((
+                tier,
+                score,
+                resource.id,
+                RecommendationItem(
+                    resource_id=resource.id,
+                    title=resource.title,
+                    provider=resource.provider,
+                    url=resource.url,
+                    type=resource.type,
+                    difficulty_level=resource.difficulty_level,
+                    duration=resource.duration,
+                    rating=resource.rating,
+                    relevance_score=link.relevance_score,
+                    score=round(score, 4),
+                ),
+            ))
+
+        # Primary: level tier (near before far). Secondary: composite score desc.
+        # Tertiary: resource_id asc for stable, snapshot-friendly ordering.
+        scored.sort(key=lambda t: (t[0], -t[1], t[2]))
+        top = [item.to_dict() for _, _, _, item in scored[:limit_per_skill]]
+        recommendations[skill_id] = top
+
+    return {
+        'role_id': role.id,
+        'role_name': role.role_name,
+        'recommendations': recommendations,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Role suggestion service
+# ---------------------------------------------------------------------------
+#
+# Ranks every active role by how well the user's current skills fit it, so the
+# UI can surface "Recommended for you" (top fit) above the rest of the catalog.
+# The fit reflects an uploaded resume automatically: CV → UserSkill → gap
+# analysis is already wired, so suggestions update once parsed skills are saved.
+#
+# Reuses compute_gap_report per role (no duplicated readiness math). For the
+# small curated catalog (~10 roles, ceiling ~50) the ~2 queries/role cost is
+# negligible; batch into a single RoleSkill + UserSkill pass if it ever grows.
+
+DEFAULT_TOP_MISSING = 3
+
+
+def suggest_roles(user, top_missing: int = DEFAULT_TOP_MISSING) -> dict:
+    """Return {"has_skills", "roles": [...]} ranked by skill fit.
+
+    Each role row: role_id, role_name, industry, readiness, band,
+    matched_skills/total_skills, top_missing_skills (most-severe first),
+    no_requirements. Sorted by (no_requirements last, readiness desc,
+    role_name asc) — roles with no requirements report readiness=100
+    spuriously, so they sink to the bottom rather than top the list.
+    """
+    has_skills = UserSkill.objects.filter(user_id=user.id).exists()
+
+    rows: list[dict] = []
+    for role in Role.objects.filter(is_active=True):
+        report = compute_gap_report(user, role)
+        total = len(report.gaps)
+        matched = sum(1 for g in report.gaps if g.gap_type == 'MET')
+        # report.gaps is severity-sorted, so the first non-MET names are the
+        # most critical missing skills.
+        missing = [g.skill_name for g in report.gaps if g.gap_type != 'MET']
+        rows.append({
+            'role_id': role.id,
+            'role_name': role.role_name,
+            'industry': role.industry,
+            'readiness': round(report.readiness, 2),
+            'band': report.band,
+            'matched_skills': matched,
+            'total_skills': total,
+            'top_missing_skills': missing[:top_missing],
+            'no_requirements': report.no_requirements,
+        })
+
+    rows.sort(key=lambda r: (r['no_requirements'], -r['readiness'], r['role_name']))
+    return {'has_skills': has_skills, 'roles': rows}

apps/analysis/tests/test_gap_analysis.py

@@ -0,0 +1,280 @@
+import pytest
+from django.contrib.auth import get_user_model
+from rest_framework import status
+from rest_framework.test import APIClient
+
+from apps.analysis.services import (
+    LEVEL_THRESHOLDS,
+    MANDATORY_CAP,
+    compute_gap_report,
+)
+from apps.roles.models import Role, RoleSkill, UserTargetRole
+from apps.skills.models import Skill, UserSkill
+
+User = get_user_model()
+pytestmark = pytest.mark.django_db
+
+ANALYSIS_URL = '/api/analysis/'
+
+
+@pytest.fixture
+def user():
+    return User.objects.create_user(
+        username='analysis@example.com',
+        email='analysis@example.com',
+        password='password123',
+        name='Analysis Tester',
+    )
+
+
+@pytest.fixture
+def auth_client(user):
+    client = APIClient()
+    client.force_authenticate(user=user)
+    return client
+
+
+def _skill(name, category='Programming'):
+    return Skill.objects.create(skill_name=name, category=category, difficulty_level='BEGINNER')
+
+
+def _role_with(skill_specs):
+    """skill_specs = [(skill_name, required_level, weight, is_mandatory), ...]"""
+    role = Role.objects.create(role_name=f'Role-{id(skill_specs)}', industry='Tech', is_active=True)
+    for name, level, weight, mandatory in skill_specs:
+        RoleSkill.objects.create(
+            role=role,
+            skill=_skill(name),
+            required_level=level,
+            weight=weight,
+            is_mandatory=mandatory,
+        )
+    return role
+
+
+def _set_prof(user, skill_name, proficiency, level='BEGINNER'):
+    skill = Skill.objects.get(skill_name=skill_name)
+    UserSkill.objects.update_or_create(
+        user=user, skill=skill,
+        defaults={'proficiency': proficiency, 'user_level': level},
+    )
+
+
+class TestReportToDict:
+    def test_to_dict_exposes_mandatory_cap_value(self, user):
+        # F18: the numeric cap value is exposed so the UI need not hardcode "60".
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, False)])
+        _set_prof(user, 'Python', 60)
+        d = compute_gap_report(user, role).to_dict()
+        assert d['mandatory_cap'] == MANDATORY_CAP
+
+
+class TestClassification:
+    def test_met_when_proficiency_equals_threshold(self, user):
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        _set_prof(user, 'Python', 60)
+        report = compute_gap_report(user, role)
+        assert report.gaps[0].gap_type == 'MET'
+        assert report.gaps[0].severity is None
+        assert report.gaps[0].gap == 0
+        assert report.gaps[0].satisfaction == 1.0
+
+    def test_missing_mandatory_is_critical(self, user):
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        report = compute_gap_report(user, role)
+        g = report.gaps[0]
+        assert g.gap_type == 'MISSING'
+        assert g.severity == 'CRITICAL'
+        assert g.user_proficiency == 0
+
+    def test_missing_optional_is_medium(self, user):
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, False)])
+        report = compute_gap_report(user, role)
+        assert report.gaps[0].gap_type == 'MISSING'
+        assert report.gaps[0].severity == 'MEDIUM'
+
+    def test_insufficient_mandatory_forces_high(self, user):
+        # Ratio 0.17 (low in absolute terms), but mandatory promotes to HIGH.
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        _set_prof(user, 'Python', 50)
+        g = compute_gap_report(user, role).gaps[0]
+        assert g.gap_type == 'INSUFFICIENT'
+        assert g.severity == 'HIGH'
+
+    def test_insufficient_ratio_high(self, user):
+        # U=20, T=60 → ratio = 40/60 ≈ 0.67 ≥ 0.5 → HIGH
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, False)])
+        _set_prof(user, 'Python', 20)
+        assert compute_gap_report(user, role).gaps[0].severity == 'HIGH'
+
+    def test_insufficient_ratio_medium(self, user):
+        # U=60, T=100 → ratio = 40/100 = 0.4 → MEDIUM
+        role = _role_with([('Python', 'ADVANCED', 1.0, False)])
+        _set_prof(user, 'Python', 60)
+        assert compute_gap_report(user, role).gaps[0].severity == 'MEDIUM'
+
+    def test_insufficient_ratio_low(self, user):
+        # U=85, T=100 → ratio = 0.15 < 0.25 → LOW
+        role = _role_with([('Python', 'ADVANCED', 1.0, False)])
+        _set_prof(user, 'Python', 85)
+        assert compute_gap_report(user, role).gaps[0].severity == 'LOW'
+
+    def test_thresholds_match_spec(self):
+        assert LEVEL_THRESHOLDS == {'BEGINNER': 40, 'INTERMEDIATE': 60, 'ADVANCED': 100}
+
+
+class TestReadiness:
+    def test_all_met_yields_100(self, user):
+        role = _role_with([
+            ('Python', 'INTERMEDIATE', 1.0, True),
+            ('SQL', 'BEGINNER', 1.0, False),
+        ])
+        _set_prof(user, 'Python', 60)
+        _set_prof(user, 'SQL', 40)
+        report = compute_gap_report(user, role)
+        assert report.readiness == 100.0
+        assert report.band == 'STRONG'
+        assert report.mandatory_cap_applied is False
+
+    def test_weighted_aggregation(self, user):
+        # Python weight 3, fully met (S=1). SQL weight 1, unmet (U=0, S=0).
+        # Raw = (1*3 + 0*1)/(3+1) * 100 = 75. SQL is optional, no cap.
+        role = _role_with([
+            ('Python', 'INTERMEDIATE', 3.0, False),
+            ('SQL', 'INTERMEDIATE', 1.0, False),
+        ])
+        _set_prof(user, 'Python', 60)
+        report = compute_gap_report(user, role)
+        assert report.readiness == 75.0
+        assert report.band == 'GOOD'
+
+    def test_mandatory_cap_applies(self, user):
+        # Three skills, two met heavily weighted, one mandatory at 0 → raw would
+        # be high but cap pins readiness at 60.
+        role = _role_with([
+            ('Python', 'INTERMEDIATE', 5.0, False),
+            ('SQL', 'INTERMEDIATE', 5.0, False),
+            ('Docker', 'INTERMEDIATE', 1.0, True),  # mandatory, unmet
+        ])
+        _set_prof(user, 'Python', 60)
+        _set_prof(user, 'SQL', 60)
+        report = compute_gap_report(user, role)
+        assert report.mandatory_cap_applied is True
+        assert report.readiness == MANDATORY_CAP
+        assert report.band == 'PARTIAL'
+
+    def test_mandatory_cap_not_applied_when_all_mandatory_met(self, user):
+        role = _role_with([
+            ('Python', 'INTERMEDIATE', 1.0, True),
+            ('Docker', 'BEGINNER', 1.0, False),  # optional, unmet
+        ])
+        _set_prof(user, 'Python', 60)
+        report = compute_gap_report(user, role)
+        assert report.mandatory_cap_applied is False
+        # Raw = (1.0 + 0)/2 * 100 = 50 → PARTIAL (no cap needed)
+        assert report.readiness == 50.0
+        assert report.band == 'PARTIAL'
+
+    def test_cap_not_applied_when_raw_below_cap(self, user):
+        # Mandatory unmet AND raw already below 60 — cap flag stays False.
+        role = _role_with([
+            ('Python', 'INTERMEDIATE', 1.0, True),
+            ('SQL', 'INTERMEDIATE', 1.0, True),
+        ])
+        _set_prof(user, 'Python', 30)
+        # SQL unmet → 0 sat
+        report = compute_gap_report(user, role)
+        # Raw = (30/60 + 0)/2 * 100 = 25 → WEAK
+        assert report.readiness == 25.0
+        assert report.mandatory_cap_applied is False
+        assert report.band == 'WEAK'
+
+    def test_no_requirements_returns_100(self, user):
+        role = Role.objects.create(role_name='Empty', industry='Tech', is_active=True)
+        report = compute_gap_report(user, role)
+        assert report.readiness == 100.0
+        assert report.no_requirements is True
+        assert report.gaps == []
+
+    def test_zero_weight_sum_returns_100(self, user):
+        role = _role_with([
+            ('Python', 'INTERMEDIATE', 0.0, False),
+            ('SQL', 'BEGINNER', 0.0, False),
+        ])
+        report = compute_gap_report(user, role)
+        assert report.readiness == 100.0
+        assert report.no_requirements is True
+        assert len(report.gaps) == 2
+
+
+class TestBands:
+    # With a single ADVANCED non-mandatory skill (T=100, W=1), the readiness
+    # score equals the proficiency exactly — so proficiency is the knob that
+    # lands us on each side of every band boundary.
+    @pytest.mark.parametrize('prof, expected_readiness, expected_band', [
+        (100, 100.0, 'STRONG'),
+        (85, 85.0, 'STRONG'),    # lower edge of STRONG (≥85)
+        (84, 84.0, 'GOOD'),      # just below STRONG
+        (65, 65.0, 'GOOD'),      # lower edge of GOOD (≥65)
+        (64, 64.0, 'PARTIAL'),   # just below GOOD
+        (45, 45.0, 'PARTIAL'),   # lower edge of PARTIAL (≥45)
+        (44, 44.0, 'WEAK'),      # just below PARTIAL
+        (0, 0.0, 'WEAK'),
+    ])
+    def test_band_boundaries(self, user, prof, expected_readiness, expected_band):
+        role = _role_with([('Python', 'ADVANCED', 1.0, False)])
+        _set_prof(user, 'Python', prof)
+        report = compute_gap_report(user, role)
+        assert report.readiness == pytest.approx(expected_readiness, abs=0.01)
+        assert report.band == expected_band
+
+
+class TestGapSorting:
+    def test_gaps_sorted_by_severity_then_weight(self, user):
+        role = _role_with([
+            ('Python', 'INTERMEDIATE', 1.0, True),   # MISSING CRITICAL
+            ('SQL', 'INTERMEDIATE', 5.0, False),     # MET
+            ('Docker', 'INTERMEDIATE', 2.0, False),  # MISSING MEDIUM
+        ])
+        _set_prof(user, 'SQL', 60)
+        report = compute_gap_report(user, role)
+        names = [g.skill_name for g in report.gaps]
+        # CRITICAL > MEDIUM > MET
+        assert names == ['Python', 'Docker', 'SQL']
+
+
+class TestAPI:
+    def test_requires_auth(self):
+        response = APIClient().get(ANALYSIS_URL)
+        assert response.status_code == status.HTTP_401_UNAUTHORIZED
+
+    def test_400_when_no_target_role(self, auth_client):
+        response = auth_client.get(ANALYSIS_URL)
+        assert response.status_code == status.HTTP_400_BAD_REQUEST
+
+    def test_200_with_active_target_role(self, auth_client, user):
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        UserTargetRole.objects.create(user=user, role=role, is_active=True)
+        _set_prof(user, 'Python', 60)
+        response = auth_client.get(ANALYSIS_URL)
+        assert response.status_code == status.HTTP_200_OK
+        assert response.data['role_id'] == role.id
+        assert response.data['readiness'] == 100.0
+        assert response.data['band'] == 'STRONG'
+        assert len(response.data['gaps']) == 1
+        assert response.data['gaps'][0]['gap_type'] == 'MET'
+
+    def test_role_id_override(self, auth_client, user):
+        role = _role_with([('Python', 'BEGINNER', 1.0, False)])
+        response = auth_client.get(f'{ANALYSIS_URL}?role_id={role.id}')
+        assert response.status_code == status.HTTP_200_OK
+        assert response.data['role_id'] == role.id
+
+    def test_role_id_not_found(self, auth_client):
+        response = auth_client.get(f'{ANALYSIS_URL}?role_id=99999')
+        assert response.status_code == status.HTTP_404_NOT_FOUND
+
+    def test_inactive_role_id_rejected(self, auth_client):
+        role = Role.objects.create(role_name='Old', industry='X', is_active=False)
+        response = auth_client.get(f'{ANALYSIS_URL}?role_id={role.id}')
+        assert response.status_code == status.HTTP_404_NOT_FOUND

apps/analysis/tests/test_recommendations.py

@@ -0,0 +1,334 @@
+"""Unit tests for the recommendation ranking service + endpoint.
+
+See research/08-next-modules-build-plan.md §Module A. Logic under test lives
+in apps.analysis.services.compute_recommendations.
+"""
+import pytest
+from django.contrib.auth import get_user_model
+from rest_framework.test import APIClient
+
+from apps.analysis.services import compute_recommendations
+from apps.resources.models import Resource, SkillResource
+from apps.roles.models import Role, RoleSkill, UserTargetRole
+from apps.skills.models import Skill, UserSkill
+
+User = get_user_model()
+pytestmark = pytest.mark.django_db
+
+RECS_URL = '/api/recommendations/'
+
+
+@pytest.fixture
+def user():
+    return User.objects.create_user(
+        username='recs@example.com',
+        email='recs@example.com',
+        password='password123',
+        name='Recs Tester',
+    )
+
+
+@pytest.fixture
+def auth_client(user):
+    client = APIClient()
+    client.force_authenticate(user=user)
+    return client
+
+
+def _skill(name, category='Programming'):
+    return Skill.objects.create(
+        skill_name=name, category=category, difficulty_level='BEGINNER',
+    )
+
+
+def _role_with(skill_specs, name_hint='Role'):
+    role = Role.objects.create(
+        role_name=f'{name_hint}-{id(skill_specs)}',
+        industry='Tech', is_active=True,
+    )
+    for name, level, weight, mandatory in skill_specs:
+        RoleSkill.objects.create(
+            role=role, skill=_skill(name),
+            required_level=level, weight=weight, is_mandatory=mandatory,
+        )
+    return role
+
+
+def _set_prof(user, skill_name, proficiency, level='BEGINNER'):
+    skill = Skill.objects.get(skill_name=skill_name)
+    UserSkill.objects.update_or_create(
+        user=user, skill=skill,
+        defaults={'proficiency': proficiency, 'user_level': level},
+    )
+
+
+def _resource(title, r_type, difficulty='INTERMEDIATE', rating=3.5, url=None,
+              duration=60):
+    return Resource.objects.create(
+        title=title,
+        provider='TestProvider',
+        url=url or f'https://example.com/{title.replace(" ", "-").lower()}',
+        difficulty_level=difficulty,
+        duration=duration,
+        type=r_type,
+        rating=rating,
+    )
+
+
+def _link(skill_name, resource, relevance=1.0):
+    SkillResource.objects.create(
+        skill=Skill.objects.get(skill_name=skill_name),
+        resource=resource, relevance_score=relevance,
+    )
+
+
+class TestRanking:
+    def test_type_preference_weight_order(self, user):
+        """Equal rating/relevance/difficulty → VIDEO > COURSE > ARTICLE > DOCS."""
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        for ttype in ('VIDEO', 'COURSE', 'ARTICLE', 'DOCS'):
+            _link('Python', _resource(
+                f'{ttype} res', ttype,
+                difficulty='INTERMEDIATE', rating=3.5,
+            ), relevance=0.8)
+
+        skill_id = Skill.objects.get(skill_name='Python').id
+        rec = compute_recommendations(user, role, limit_per_skill=10)
+        order = [r['type'] for r in rec['recommendations'][skill_id]]
+        assert order == ['VIDEO', 'COURSE', 'ARTICLE', 'DOCS']
+
+    def test_difficulty_matches_user_level_beginner(self, user):
+        """Difficulty is anchored to the USER's current level, not the role's
+        required level. A junior (proficiency 30 → BEGINNER) on an
+        INTERMEDIATE-required skill gets BEGINNER material first, ADVANCED last."""
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        _set_prof(user, 'Python', 30)  # BEGINNER level, still < 60 → INSUFFICIENT
+        for diff in ('BEGINNER', 'INTERMEDIATE', 'ADVANCED'):
+            _link('Python', _resource(
+                f'{diff} course', 'COURSE', difficulty=diff, rating=3.5,
+            ), relevance=0.8)
+
+        skill_id = Skill.objects.get(skill_name='Python').id
+        rec = compute_recommendations(user, role, limit_per_skill=10)
+        order = [r['difficulty_level'] for r in rec['recommendations'][skill_id]]
+        assert order[0] == 'BEGINNER'
+        assert order[-1] == 'ADVANCED'
+
+    def test_difficulty_anchor_follows_higher_user_level(self, user):
+        """The anchor moves with the user: an INTERMEDIATE learner (proficiency
+        55) on an ADVANCED-required skill gets INTERMEDIATE material first —
+        proving the match follows the user, not the role's required level."""
+        role = _role_with([('Python', 'ADVANCED', 1.0, True)])
+        _set_prof(user, 'Python', 55)  # INTERMEDIATE level, still < 100 → INSUFFICIENT
+        for diff in ('BEGINNER', 'INTERMEDIATE', 'ADVANCED'):
+            _link('Python', _resource(
+                f'{diff} course', 'COURSE', difficulty=diff, rating=3.5,
+            ), relevance=0.8)
+
+        skill_id = Skill.objects.get(skill_name='Python').id
+        rec = compute_recommendations(user, role, limit_per_skill=10)
+        first = rec['recommendations'][skill_id][0]
+        assert first['difficulty_level'] == 'INTERMEDIATE'
+
+    def test_relevance_score_tiebreaker(self, user):
+        """Two COURSE rows same rating/difficulty → higher relevance wins."""
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        low = _resource('low-rel', 'COURSE', rating=3.5)
+        high = _resource('high-rel', 'COURSE', rating=3.5)
+        _link('Python', low, relevance=0.3)
+        _link('Python', high, relevance=0.9)
+
+        skill_id = Skill.objects.get(skill_name='Python').id
+        rec = compute_recommendations(user, role, limit_per_skill=10)
+        titles = [r['title'] for r in rec['recommendations'][skill_id]]
+        assert titles[0] == 'high-rel'
+
+    def test_rating_tiebreaker(self, user):
+        """Two COURSE rows same relevance → higher rating wins."""
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        low = _resource('low-rating', 'COURSE', rating=2.0)
+        high = _resource('high-rating', 'COURSE', rating=5.0)
+        _link('Python', low, relevance=0.8)
+        _link('Python', high, relevance=0.8)
+
+        skill_id = Skill.objects.get(skill_name='Python').id
+        rec = compute_recommendations(user, role, limit_per_skill=10)
+        titles = [r['title'] for r in rec['recommendations'][skill_id]]
+        assert titles[0] == 'high-rating'
+
+    def test_deterministic_tie_break_by_id(self, user):
+        """Two identical rows → lower resource_id comes first so snapshots are stable."""
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        first = _resource('first', 'COURSE', rating=3.5, url='https://e.com/a')
+        second = _resource('second', 'COURSE', rating=3.5, url='https://e.com/b')
+        _link('Python', first, relevance=0.8)
+        _link('Python', second, relevance=0.8)
+        assert first.id < second.id
+
+        skill_id = Skill.objects.get(skill_name='Python').id
+        rec = compute_recommendations(user, role, limit_per_skill=10)
+        ids = [r['resource_id'] for r in rec['recommendations'][skill_id]]
+        assert ids == [first.id, second.id]
+
+    def test_relevance_can_override_type_preference(self, user):
+        """Very-relevant DOCS (1.0) should beat low-relevance VIDEO (0.3) —
+        this is the documented behavior from the ranking design."""
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        video = _resource('sparse video', 'VIDEO', rating=3.5)
+        docs = _resource('perfect docs', 'DOCS', rating=3.5)
+        _link('Python', video, relevance=0.3)
+        _link('Python', docs, relevance=1.0)
+
+        skill_id = Skill.objects.get(skill_name='Python').id
+        rec = compute_recommendations(user, role, limit_per_skill=10)
+        titles = [r['title'] for r in rec['recommendations'][skill_id]]
+        assert titles[0] == 'perfect docs'
+
+    def test_far_level_resource_never_outranks_nearer_one(self, user):
+        """Level-tier guarantee: a resource 2 levels off the user's current
+        level ("far") can never outrank one within 1 level ("near"), even when
+        the far resource wins on type, relevance AND rating.
+
+        Regression for the seeded-SQL case where an ADVANCED course (higher
+        type/relevance) edged an INTERMEDIATE doc for a BEGINNER learner."""
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        _set_prof(user, 'Python', 30)  # BEGINNER anchor
+        # near (1 level off): deliberately the WEAKER resource on every other axis
+        near = _resource('intermediate docs', 'DOCS',
+                         difficulty='INTERMEDIATE', rating=4.0)
+        # far (2 levels off): stronger type + relevance + rating
+        far = _resource('advanced course', 'COURSE',
+                        difficulty='ADVANCED', rating=5.0)
+        _link('Python', near, relevance=0.7)
+        _link('Python', far, relevance=1.0)
+
+        skill_id = Skill.objects.get(skill_name='Python').id
+        rec = compute_recommendations(user, role, limit_per_skill=10)
+        order = [r['difficulty_level'] for r in rec['recommendations'][skill_id]]
+        assert order == ['INTERMEDIATE', 'ADVANCED']
+
+
+class TestFilteringAndShape:
+    def test_met_skills_excluded(self, user):
+        role = _role_with([
+            ('Python', 'INTERMEDIATE', 1.0, True),     # we'll MET this
+            ('SQL', 'INTERMEDIATE', 1.0, True),        # gap
+        ])
+        _set_prof(user, 'Python', 60)   # == threshold → MET
+        _link('Python', _resource('py docs', 'DOCS'), relevance=1.0)
+        _link('SQL', _resource('sql docs', 'DOCS'), relevance=1.0)
+
+        python_id = Skill.objects.get(skill_name='Python').id
+        sql_id = Skill.objects.get(skill_name='SQL').id
+        rec = compute_recommendations(user, role)
+        assert python_id not in rec['recommendations']
+        assert sql_id in rec['recommendations']
+
+    def test_top_n_per_skill(self, user):
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        for i in range(10):
+            _link('Python', _resource(
+                f'r{i}', 'COURSE', url=f'https://e.com/{i}',
+            ), relevance=0.8)
+
+        skill_id = Skill.objects.get(skill_name='Python').id
+        rec = compute_recommendations(user, role, limit_per_skill=3)
+        assert len(rec['recommendations'][skill_id]) == 3
+
+    def test_empty_catalog_returns_empty_per_gap(self, user):
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        skill_id = Skill.objects.get(skill_name='Python').id
+        rec = compute_recommendations(user, role)
+        assert rec['recommendations'][skill_id] == []
+
+    def test_no_gaps_returns_empty_map(self, user):
+        """User with zero gaps (or role with no requirements) gets an empty
+        recommendations map, not an error."""
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        _set_prof(user, 'Python', 100)
+        rec = compute_recommendations(user, role)
+        assert rec['recommendations'] == {}
+
+
+class TestEndpoint:
+    def test_endpoint_uses_active_target_role(self, user, auth_client):
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        UserTargetRole.objects.create(user=user, role=role, is_active=True)
+        _link('Python', _resource('py course', 'COURSE'), relevance=0.8)
+
+        r = auth_client.get(RECS_URL)
+        assert r.status_code == 200, r.data
+        assert r.data['role_id'] == role.id
+        skill_id = Skill.objects.get(skill_name='Python').id
+        assert skill_id in [int(k) for k in r.data['recommendations']]
+
+    def test_endpoint_no_target_no_param_returns_400(self, auth_client):
+        r = auth_client.get(RECS_URL)
+        assert r.status_code == 400
+        assert 'target role' in r.data['detail'].lower()
+
+    def test_endpoint_role_param_overrides_target(self, user, auth_client):
+        a = _role_with([('Python', 'INTERMEDIATE', 1.0, True)], name_hint='A')
+        b = _role_with([('SQL', 'INTERMEDIATE', 1.0, True)], name_hint='B')
+        UserTargetRole.objects.create(user=user, role=a, is_active=True)
+        _link('Python', _resource('py c', 'COURSE'), relevance=0.8)
+        _link('SQL', _resource('sql c', 'COURSE'), relevance=0.8)
+
+        r = auth_client.get(f'{RECS_URL}?role={b.id}')
+        assert r.status_code == 200
+        assert r.data['role_id'] == b.id
+
+    def test_endpoint_limit_query_param(self, user, auth_client):
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        UserTargetRole.objects.create(user=user, role=role, is_active=True)
+        for i in range(5):
+            _link('Python', _resource(
+                f'r{i}', 'COURSE', url=f'https://e.com/{i}',
+            ), relevance=0.8)
+
+        r = auth_client.get(f'{RECS_URL}?limit=2')
+        assert r.status_code == 200
+        skill_id = Skill.objects.get(skill_name='Python').id
+        assert len(r.data['recommendations'][skill_id]) == 2
+
+    def test_endpoint_rejects_invalid_limit(self, user, auth_client):
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        UserTargetRole.objects.create(user=user, role=role, is_active=True)
+
+        r = auth_client.get(f'{RECS_URL}?limit=0')
+        assert r.status_code == 400
+
+        r = auth_client.get(f'{RECS_URL}?limit=abc')
+        assert r.status_code == 400
+
+    def test_endpoint_empty_for_fully_met_user(self, user, auth_client):
+        role = _role_with([('Python', 'BEGINNER', 1.0, True)])
+        UserTargetRole.objects.create(user=user, role=role, is_active=True)
+        _set_prof(user, 'Python', 100)
+
+        r = auth_client.get(RECS_URL)
+        assert r.status_code == 200
+        assert r.data['recommendations'] == {}
+
+    def test_endpoint_clamps_huge_limit(self, user, auth_client):
+        """An adversarial ?limit=100000 is clamped to MAX_LIMIT_PER_SKILL, not
+        passed through verbatim. With more links than the cap, the per-skill
+        list never exceeds MAX_LIMIT_PER_SKILL."""
+        from apps.analysis.services import MAX_LIMIT_PER_SKILL
+
+        role = _role_with([('Python', 'INTERMEDIATE', 1.0, True)])
+        UserTargetRole.objects.create(user=user, role=role, is_active=True)
+        for i in range(MAX_LIMIT_PER_SKILL + 10):
+            _link('Python', _resource(
+                f'r{i}', 'COURSE', url=f'https://e.com/{i}',
+            ), relevance=0.8)
+
+        r = auth_client.get(f'{RECS_URL}?limit=100000')
+        assert r.status_code == 200, r.data
+        skill_id = Skill.objects.get(skill_name='Python').id
+        assert len(r.data['recommendations'][skill_id]) == MAX_LIMIT_PER_SKILL
+
+    def test_endpoint_requires_authentication(self):
+        client = APIClient()
+        r = client.get(RECS_URL)
+        assert r.status_code == 401