Feature: AI Learning Tools — Centralized Architecture & Reusable Component System

Metadata

• Issue ID: FEAT-61
• Status: Done
• Owner: danrave1234
• Related PRs: 61-ai-learning-tools-reusable-component-system -> dev (StudyBoostIO/StudyboostV2#61)

---

Overview

FEAT-61 completes the AI architecture in three layers:

1. Backend centralization — a typed, extensible AI tool registry so adding a new AI tool requires no changes to the controller or processor.
2. Frontend primitives — DocumentPicker, AiPageShell, and the useAiTool hook replace the former AiToolWorkspace monolith.
3. Gamification foundation — TriviaGameTool as the first game-type tool, establishing the pattern for the later game tools (typing, crossword, letter tile, hangman).

It builds on FEAT-60 (which delivered Flashcards, Summary, GeminiGenerationProvider, the AI job queue, and the plan-access guard). FEAT-61 adds the Q&A Tool, the Study Guide Tool, the IAiTool interface + BaseAiTool base class, AiToolRegistryService, the dynamic POST /ai/tools/:toolId controller, the standalone GeminiModule, the frontend primitives, and TriviaGameTool.

Canonical feature doc: docs/features/FEAT-61-AI-Learning-Tools-Reusable-Component-System.md.

---

Frontend Behavior

Primitive components

UI states and interactions

• Loading — while an AI request is in-flight, AiToolBase shows a spinner and disables the trigger.
• Error — failed requests render a retryable error state with a "Try again" affordance.
• Document ingest — DocumentPicker uploads files via POST /documents/upload, then fires onDocumentsIngested(ids[]); pages can auto-trigger their tool once docs are ingested.
• Result rendering — each tool page composes a tool-specific result component (SummaryComponent, FlashcardsComponent, QnAComponent, StudyGuideComponent).

Validation rules

• Q&A pages require a non-empty user_query before the request fires.
• Tool pages that require a scope (Q&A, study guide) do not trigger until at least one document is ingested.

AI tool pages

AiToolWorkspace and AiToolTrigger were removed — superseded by the reusable primitives.

---

Backend Behavior

Tool registry pattern

All AI tools implement IAiTool and extend BaseAiTool. BaseAiTool.run() calls the tool's execute() then deducts one AI credit unless DEV_BYPASS_SUBSCRIPTION=true. Tools are registered in AiModule as AI_TOOL_REGISTRY multi-providers; AiToolRegistryService builds a Map<toolId, IAiTool> injected into AiToolsController and AiProcessingProcessor (no switch statement).

GeminiModule is a standalone module exporting GeminiGenerationProvider, imported by both AiModule and DocumentsModule to avoid circular dependencies. DocumentsService uses GeminiGenerationProvider instead of an inline fetch to Gemini.

Tool DTO formats

Endpoint map

All AI routes carry AiThrottlerGuard at the controller level (20 requests / hour per user bucket) plus cookie auth and plan access.

Business logic and failure modes

• AiScopeResolverService enforces document/course ownership; users can only resolve chunks from material they own.
• TriviaGameTool stores generated questions in ai_game_sessions.questions (JSONB) with correctIndex + explanation; the API response strips both, sending only question + options[]. submitAttempt() scores client answers server-side and reveals explanations.
• Q&A is stateless — no persistence table. Semantic retrieval uses resolveWithEmbeddings() (cosine-similarity ranking, positional fallback).
• Empty document or empty course scope -> tool returns 422 Unprocessable Entity.
• Malformed LLM JSON -> tool throws 500 with a safe error message.

Database tables

Migrations are hand-written SQL applied via pnpm run migrate:prod.

---

QA Test Scenarios

---

Edge Cases

• Empty document (no chunks ingested) -> tool returns 422 Unprocessable Entity.
• Course with zero documents -> scope resolver returns empty, tool returns 422.
• LLM returns malformed JSON -> tool throws 500 with a safe error message.
• Very large document scope -> scope resolver caps total characters at MAX_TOTAL_CHARACTERS.
• DEV_BYPASS_SUBSCRIPTION=true -> credit deduction skipped; all tools remain functional.
• AI request in-flight -> AiToolBase shows a loading spinner and disables the trigger.
• AI request fails -> retryable error state with "Try again".
• Network failure during DocumentPicker upload -> upload error surfaced; onDocumentsIngested does not fire.

---

Notes

• Dependencies: FEAT-60 (GeminiGenerationProvider, job queue, embedding pipeline, plan-access guard), FEAT-31 (CookieAuthGuard), FEAT-39 (PlanAccessGuard, @RequireFeature('AI_CREDIT')).
• Q&A has no persistence table — answers are stateless by design.
• Adding a new AI tool requires no controller or processor changes — register it in AiModule.providers + the AI_TOOL_REGISTRY multi-provider factory.
• The project uses manual SQL migrations + pnpm run migrate:prod; never prisma migrate dev on the shared Neon branch.

---

Adding a New AI Tool (Checklist)

1. backend/src/ai/tools/<name>.tool.ts — extend BaseAiTool, set readonly toolId, implement protected execute().
2. backend/src/ai/dto/generate-<name>.dto.ts — validated DTO.
3. AiModule — add the tool to providers + the AI_TOOL_REGISTRY multi-provider factory.
4. Migration (if needed) — write SQL with the required header block, run pnpm run migrate:prod.
5. frontend/app/(features)/ai/<name>/page.tsx — "use client", compose AiPageShell + DocumentPicker + useAiTool + a result component.

No change to dynamic generation routing is required as long as the tool is registered in AiModule.

---

Security Notes

• No AI endpoint accepts an arbitrary user_id; identity always comes from cookie auth context.
• AiScopeResolverService enforces ownership of documents/courses.
• BaseAiTool.run() deducts one AI credit per successful generation (skipped when DEV_BYPASS_SUBSCRIPTION=true).
• All tool endpoints are rate-limited at 20 requests / hour via AiThrottlerGuard.