[PB-008] AI Features

[ma7moudalysalem]

Owner: @ma7moudalysalem
Spec: .specify/specs/PB-008-ai-features/
SRS: US-082..US-087

IAiService + StubAiService in place. Swap to OpenAI or Azure OpenAI.
Every response must carry an AI disclaimer (FR-121).

[ma7moudalysalem]

Status — full stack done, open pending QA sign-off + optional model switch

PB-008 ships with both a deterministic local provider and a real OpenAI provider behind a single config flag. Issue stays open until the final QA checklist runs end-to-end in staging.

Backend (10/10 done)

Task	Commit	Notes
T-001 IAiService + default impl	16d9046, 659fea0	interface was scaffolded; LocalAiService replaces the empty stub with real scoring
T-002 AiInteraction entity + config	16d9046	landed with initial migration, tracks feature/provider/model/tokens/cost/error
T-003 GenerateRecommendationsCommand	db8adb9	persists interaction row, hydrates scholarship titles for the UI, counts against cost budget
T-004 GetMyRecommendationsQuery cache	7d87794	reads last successful row within max-age; 204 on miss
T-005 CheckEligibilityCommand	db8adb9	per-criterion yes/partial/no/unknown, summary text
T-006 AskChatbotCommand w/ session	db8adb9	sessionId roundtripped, scoped system prompt, domain-bounded
T-007 OpenAiService provider	7b3fa6b	plain HttpClient+System.Text.Json; chat is full-LLM, recs get LLM rewrite of local-scored explanations, eligibility stays 100% local. Falls back to Local on network failure
T-008 PII redaction	db8adb9	source-generated regex — email / credit card / phone applied before persist or provider dispatch
T-009 Daily cost limit per user	db8adb9	AiCostGate — rolling 24h sum vs DailyUserCostLimitUsd (default $1), conflict throw
T-010 Tests	db8adb9, 948eebc	16 tests: PII redaction across 3 patterns, validator rules, AiCostGate against InMemory DB (5 scenarios)

Frontend (6/6 done)

Task	Commit	Notes
T-011 AiRecommendations widget	8a95758	5-item list, GET-first (cached) with auto-regen on miss, explicit refresh button always POSTs
T-012 EligibilityChecker modal	8a95758	triggered from scholarship detail, per-criterion icons, summary + disclaimer
T-013 Chatbot	8a95758	turn-based UI, sessionId preserved, cost/token hint per assistant reply
T-014 AiDisclaimer reusable	8a95758	consistent "verify with official sources" footer on every AI surface
T-015 MatchScoreBadge + eligibility breakdown	8a95758	tiered colors 0-100; eligibility breakdown embedded in the modal
T-016 Arabic copy	8a95758	full ai.json AR namespace

QA

Task	Status	Notes
T-017 E2E: recs load / eligibility returns / chatbot round-trip	🟡 partial	Playwright route-guard smoke in client/src/test/e2e/ai.spec.ts; full-flow E2E waits on seeded staging env

Files of interest

• server/src/ScholarPath.Application/Ai/ (Commands × 3, Queries × 2, DTOs, AiCostGate)
• server/src/ScholarPath.Infrastructure/Services/LocalAiService.cs (deterministic default)
• server/src/ScholarPath.Infrastructure/Services/OpenAiService.cs (real provider)
• server/src/ScholarPath.API/Controllers/AiController.cs
• client/src/components/ai/ (5 components)
• client/src/pages/student/AiFeatures.tsx
• client/src/services/api/ai.ts
• client/src/locales/{en,ar}/ai.json

Provider swap

• default: appsettings.json leaves Ai:Provider = "Stub" → LocalAiService (offline, deterministic, free)
• prod: set Ai:Provider = "OpenAi" + Ai:OpenAi:ApiKey → real gpt-4o-mini, same interface

Done-criteria check

• ✅ Stub mode passes all tests (52/52 green)
• ✅ Real provider switchable via Ai:Provider config, no code change
• ✅ Daily cost cap enforced (default $1/user/24h rolling)
• ✅ PII never reaches a provider (redaction pass before dispatch)