# AI assist (career)

RealCredi uses **Anthropic Claude on the backend only** for CMH assist features. When AI is disabled or unavailable, the app falls back to **heuristic helpers** (same API contracts, no frontend changes required).

## Surfaces

| Feature | API | When AI runs |
|---------|-----|----------------|
| Practice prompt | `POST /career/practice` | Start of a practice round |
| Practice feedback | `POST /career/practice/:id/submit` | After learner submits an answer |
| Session summary | `POST /career/sessions/:sessionId/summary` | Coach generates follow-up summary |
| Rubric assist | `POST /career/rubric-assist` | Coach reviews a work sample |

AI-backed routes also use a stricter **rate limit** (30 requests / hour / user in production).

## Environment (backend)

Add to `backend/.env`:

```env
AI_ENABLED=true
ANTHROPIC_API_KEY=sk-ant-...
AI_MODEL=claude-haiku-4-5
AI_MAX_TOKENS=1024
AI_TIMEOUT_MS=30000
```

- **`AI_ENABLED=false`** (default): heuristics only — safe for local dev and CI without an API key.
- **`ANTHROPIC_API_KEY`**: never expose to the Next.js frontend.

See [`backend/.env.example`](https://github.com/MuseTec/RealCredi/blob/main/backend/.env.example) for defaults.

## Architecture

```
Frontend → POST /api/v1/career/...
         → CompoundLoopService / CoachingAiService
         → CareerAiAssistService → LlmService → Anthropic API
         → AiGenerationLog (audit row per attempt)
         → heuristic fallback on disable/error
```

Key backend paths:

- `backend/src/services/ai/llm.service.ts` — provider, timeout, retry, audit
- `backend/src/services/ai/career-ai-assist.service.ts` — prompt templates + JSON parsing
- `backend/src/services/career-loop/compound.service.ts` — practice
- `backend/src/services/career-loop/coaching-ai.service.ts` — summaries + rubric

## CMH guardrails

From MVP scope:

- AI **assists** coaches and learners — it does **not** verify skills, issue credentials, or make hire decisions.
- Practice feedback and rubric assist are **draft starting points**; human coach review remains required.
- Session summaries are **drafts**; coaches should edit before sharing.
- Prompts instruct the model not to claim verification or hire-readiness.

## Audit logging

Each LLM attempt writes an **`AiGenerationLog`** row:

- `feature`, `model`, `success`, token counts, latency
- Truncated, sanitized request/response previews (emails/phones redacted)

Phase 1 is write-only audit in the database. Admins can browse logs at **`/admin/career/ai-logs`** (setup status, stats, filters, request/response previews).

## Related docs

- [Career (CMH learner)](./career.md)
- [Coaching](./coaching.md)
- [Architecture: career loop](../architecture/career-loop.md)