# AI Assessments Hub

Public assessment APIs are the unified hub only (legacy per-type routes removed):

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/api/v1/ai/generate` | Build assessment content (not stored in Gateway DB) |
| POST | `/api/v1/ai/evaluate` | Grade submission + **persist attempt** (all 4 types) |

`/ai/code/judge` is **disabled** — Platform grades coding via `/ai/evaluate`.

Auth: `X-Internal-Token`.

## Generate (`POST /ai/generate`)

### assessment_type (exactly 4)

| Value | Meaning |
|-------|---------|
| `coding_challenge` | Coding / technical coding screen |
| `aptitude_and_reasoning` | Aptitude & reasoning |
| `personality_eval` | Personality / culture-fit style eval |
| `role_case_play` | Role case play (case + scenarios) |

### question_type (exactly 3)

`mcq` | `short_answer` | `mcq_and_short_answer`

### Other required fields

Same body for every `assessment_type`:

```json
{
  "assessment_type": "coding_challenge",
  "question_type": "mcq",
  "assessment_name": "Backend Screen",
  "linked_job": "job-be-001",
  "duration": 30,
  "difficulty": "moderate",
  "number_of_questions": 5,
  "passing_score": 70
}
```

**Job grounding:** loads role title, JD (`markdown` / sections), and skills from `ai_jobs` via `linked_job`, then generates questions from that JD. Unknown job → **404**. Empty JD → **422**.

**Storage:** generate response is **not** written to Gateway DB. Platform must persist `assessmentId` + `answer_key` / questions.

## Evaluate (`POST /ai/evaluate`)

Aligned with Platform submission flow.

### Required

| Field | Notes |
|-------|--------|
| `assessmentId` | From generate |
| `candidateId` | Platform candidate |
| `assessmentType` | Same 4 types as generate (incl. `personality_eval`, `role_case_play`) |
| `timeTaken` | Seconds |
| `passingScore` | 0–100 |
| `questions[]` | Each: `questionId`, candidate `answer`, `expectedAnswer` (from Platform-held key) |

`personality_eval` and `role_case_play` use **the same evaluate body** — set `assessmentType` accordingly and send scenario/task questions with answers + expected keys from generate.

### Optional

`submissionId` — Platform submission / attempt correlation id.

### Persistence (yes — fits Platform design)

| Layer | Owns |
|-------|------|
| **Platform** | Candidate CRM, which assessment was assigned, full generate payload / keys |
| **Gateway** | Scores the attempt and stores **`candidate_assessment_attempts`** keyed by `candidate_id` + `assessment_id` |

When evaluate succeeds with `candidateId`, Gateway sets `persisted=true` and returns `attemptId`. Results surface on `GET /candidates/{id}/performance?action=assessments`.
