M09: AI Study Assistant
Phase: P2: Scholar Features Target: Weeks 28–32 Sprints: S13 (Weeks 27–28, shared with M08), S14 (Weeks 29–30) Release:
web/v0.9.0-alpha,ai/v0.1.0-alpha
Phase Context
Goal: The three paid pillars that justify $79.99/year — interlinear Hebrew/Greek + JST, constellation view, and constrained AI. Ref: MVP.md § Paid Tier.
Key constraint: Founding users enter during this phase (~Week 22). Ship incrementally; don't wait for "complete."
ZenHub Configuration
| Field | Value |
|---|---|
| Milestone | M09: AI Study Assistant |
| Due Date | 2026-10-18 |
| Default Pipeline | Product Backlog |
| Primary Epic(s) | AI Study Assistant |
Prerequisites
| Prerequisite | Source | Why Needed |
|---|---|---|
| M02: Content API serving | P0 | AI needs passage context to generate explanations and study questions |
| M03: Scripture Reader | P1 | AI panel lives in the web app reader interface |
| M05: Staging environment | P1 | Founding users are already using staging during P2 |
⚠️ Important: AI ships without Scholar entitlement gating. Entitlement enforcement is added in M10 (Billing & Subscriptions epic) when billing goes live. During M09, AI endpoints are auth-required but not plan-gated.
Epic: AI Study Assistant
9 story areas. Constrained AI Q&A about the current passage with scripture and lexicon citations.
| Story Area | Scope | Spec Reference |
|---|---|---|
| LLM client ABC | Abstract LLMClient with Anthropic (primary) + OpenAI (fallback) | TECH-SPEC.md § AI Service |
| Prompt templates | Jinja2 .j2 files for explain, questions, "what does original language reveal" | MVP.md § Priority #3 |
| Caching decorator | Redis semantic caching by prompt hash | TECH-SPEC.md § AI Service |
| AI routes | POST /ai/explain, POST /ai/questions | TECH-SPEC.md § API Endpoints |
| Session limiting | 10 sessions/month on Scholar tier (counter in Redis) | MVP.md § Priority #3 |
| Citation linking | AI responses reference passages + lexicon entries as tappable links | MVP.md § Priority #3 |
| AI UI | StudyAssistant panel, prompt template buttons, response display | DESIGN-SYSTEM.md § P4 Components |
| Gateway AI routing | Route /api/v1/ai/* → AI service; auth-required but Scholar entitlement gating deferred to M10 (Billing & Subscriptions) | TECH-SPEC.md § Gateway |
| AI icon | ai-assistant spark/four-pointed star icon | DESIGN-SYSTEM.md § Navigation Icons |
Document References
| Doc | Contains | Use When Writing Stories For |
|---|---|---|
| MVP.md | Feature scope, tier breakdown, success criteria, budget | Acceptance criteria, scope boundaries |
| TECH-SPEC.md | Architecture, service boundaries, data stores, API catalog | Technical implementation details |
| GOSPELIB-SCHEMAS.md | All 7 schema families, node/edge types, validation rules | Data models, Pydantic models, graph schema |
GOSPELIB-INGEST-SPEC.md | 7-stage pipeline, Cypher templates, batch strategy, CLI | Ingest pipeline stories |
| DESIGN-SYSTEM.md | Visual identity, component catalog, reader modes, tokens | UI component stories |
| DESIGN-SYSTEM.md §§ 13, 21–23 | Footnotes (§13), subscription boundaries (§21), sharing (§22), onboarding (§23) | UX flow stories |
| Deployment & Operations | Environments, K8s, CI/CD, migrations, secrets, DR | Infrastructure and deployment stories |
| REPO-MAP.md | Directory structure, naming conventions, dependency rules | All stories (coding standards) |
Additional Spec References for M09
- MVP.md § Priority #3 — AI study assistant feature definition, session limits, citation requirements
- TECH-SPEC.md § AI Service — AI service architecture, LLM client pattern, caching strategy
- TECH-SPEC.md § API Endpoints — AI route contracts
- DESIGN-SYSTEM.md § P4 Components — StudyAssistant panel UI spec
Sprint Mapping
| Sprint | Weeks | Primary Focus |
|---|---|---|
| S13 | 27–28 | Constellation polish (M08 overlap), AI LLM client + prompts |
| S14 | 29–30 | AI routes + caching + UI, session limiting, gateway AI routing |
Note: S13 is shared with M08 (Knowledge Graph). The first half finishes constellation polish; the second half begins AI work. S14 overlaps with the start of M10 (P3).
Sprint Load Warnings
No specific sprint load warnings from the plan target S13–S14 directly. However:
- S14 (Weeks 29–30) is the P2→P3 transition sprint. AI work must finish alongside the start of billing work (M10).
- Founding users are active and providing feedback throughout this period — budget capacity for bug fixes and user-reported issues.
Release Info
| Release | Tag | Trigger | Contains |
|---|---|---|---|
v0.9.0-alpha | web/v0.9.0-alpha, ai/v0.1.0-alpha | M09 complete | AI study assistant (Scholar) |
Tags follow <component>/v<semver> per release-please-config.json.
Note: This is the first release of the AI service (
ai/v0.1.0-alpha).
Relevant Risks
| Risk | Impact | Mitigation |
|---|---|---|
| AI cost overruns | Monthly API costs exceed budget | Session limiting, prompt caching, Anthropic's caching API, cost monitoring |
| Solo founder velocity | 38-week plan too aggressive | Founding users at Week 22 provide feedback before full scope; cut P3 scope if needed |
Cross-Cutting Concerns
Testing
| Layer | Framework | When | Spec Reference |
|---|---|---|---|
| Python unit/integration | pytest + testcontainers | Every PR | GOSPELIB-INGEST-SPEC.md § Testing |
| Go unit | go test -race + table-driven | Every PR (gateway AI routing) | TECH-SPEC.md § Testing |
| TypeScript unit | Vitest | Every PR | TECH-SPEC.md § Testing |
| Component visual | Storybook or playground | P1+ | DESIGN-SYSTEM.md § Governance |
| Visual regression | Playwright + pixelmatch | P1+ (any packages/ui/ or apps/*/src/ change) | DESIGN-SYSTEM.md § Visual Regression CI |
Documentation
| Doc | Update Trigger |
|---|---|
| API OpenAPI specs | AI service endpoints added (auto-generated by FastAPI) |
| ADRs | LLM provider selection rationale, caching strategy decisions |
CI/CD
Staging CD pipeline and Sentry should be live (activated in M05). AI service needs to be added to the staging deployment pipeline. Python test containers in CI should already be configured (from P0).
M09→M10 Entitlement Gating Note
During M09, the AI service endpoints are auth-required (user must be logged in) but not plan-gated (any authenticated user can access). This is intentional:
- M09 ships AI functionality without billing infrastructure
- M10 (Billing & Subscriptions) adds the entitlement middleware to the gateway
- Once M10 is complete, AI endpoints (along with interlinear, constellation, etc.) will require an active Scholar subscription
This means during the window between M09 and M10 completion, all authenticated users have Scholar-level access to AI features.
Dependencies
Upstream (what M09 needs)
| Dependency | Milestone | Detail |
|---|---|---|
| Content API with passage data | M02 | AI needs passage context for explain/questions prompts |
| Reader shell with panels | M03 | StudyAssistant panel UI lives in the reader |
| Staging environment | M05 | AI service deployed to staging for founding user testing |
Downstream (what depends on M09)
| Dependent | Milestone | Detail |
|---|---|---|
| M10 entitlement gating | M10 | Scholar entitlement middleware gates AI endpoints |
| M11 performance audit | M11 | AI response times included in performance audit |
| M11 analytics | M11 | AI session usage tracking for leading indicators |
Epic: AI Study Assistant — Issues
| Issue | Title | Status | Notes |
|---|---|---|---|
| M09-001 | Implement Abstract LLMClient ABC with Anthropic and OpenAI Providers | ✅ Done | LLMClient ABC, AnthropicClient, OpenAIClient, create_llm_client factory + unit tests |
| M09-002 | Create Jinja2 Prompt Templates for AI Study Actions | ✅ Done | explain_passage.j2, study_questions.j2, original_language.j2, PromptRenderer + unit tests |
| M09-003 | Implement Redis Semantic Caching Decorator for LLM Responses | ✅ Done | CachingLLMClient decorator + db/redis.py factory + unit tests |
| M09-004 | Implement AI Routes — POST /ai/explain and POST /ai/study-questions | ✅ Done | AIService, routes/ai.py, models/ai.py, dependencies.py, integration tests |
| M09-005 | Implement Session Limiting — 10 AI Sessions per Month | ✅ Done | SessionLimiter, GET /ai/sessions/remaining, wired into explain/study-questions |
| M09-006 | Implement Citation Linking in AI Responses | ✅ Done | CitationParser, CitationValidator, integrated into AIService |
| M09-007 | Build AI StudyAssistant Panel UI | ✅ Done | AIStudyPanel, AIResponseCard, AIStudyPanelContainer, SDK AiResource, web AppShell integration |
| M09-008 | Add Gateway AI Route Proxy — /api/v1/ai/* → AI Service | ✅ Done | AIServiceURL config, RateLimitAI, /api/v1/ai/* proxy mount, config_test.go, router_test.go AI cases |
| M09-009 | Design and Export ai-assistant Icon | ✅ Done | GlAiAssistantIcon (line + filled) already present in GlIcons.tsx |
| M09-010 | services/ai FastAPI Scaffold (Provider-Abstracted LLM Endpoint, Corpus Filter, OTel) | ❌ To Do | Authored W0.1 R3 (2026-04-17) — closes the gap where M25-003 / M21-006 / M21-008 all referenced services/ai but no issue owned the provider-abstracted scaffold, citation extraction, and per-tenant rate limiting |
Progress: 9 Done · 0 Partial · 1 To Do (90%)
W0.1 R3 (2026-04-17): M09-010 authored. The milestone's original 9 issues target the entitlement-gated
services/aiv1 endpoints (/ai/explain,/ai/study-questions) built against the LLMClient ABC. M09-010 extends that service into a production scaffold with/v1/assistant/query+/v1/assistant/stream, a formalAIProviderProtocol (replacing the ad-hoc LLMClient ABC), corpus-filter injection, citation extraction, and OpenTelemetry cost/latency attributes — consumed by M21-006/008 and M25-003 downstream.
Issues
Issue Dependency Graph
M09-001 ──► M09-002 ──► M09-004 ─ ─► M09-005 ──► M09-007
M09-001 ──► M09-003 ──► M09-004 ──► M09-006 ──► M09-007
M09-001 ──► M09-004
M09-008 ──► M09-007
M09-009 ──► M09-007
M10-001 ─┐
M15-013 ─┴──► M09-010 ──► M21-006, M21-008, M25-003
Legend:
A ──► Bmeans A blocks B (B is blocked by A)
Summary
| Metric | Count |
|---|---|
| Total Issues | 10 |
| Sub-Issues | 0 |
| Total Estimate (pts) | 42 |
| Sprints | S13–S14 |
| Dependencies (blocking) | 11 |
| Dependencies (blocked by) | 11 |