Skip to main content

AI Study Assistant

The AI study assistant provides LLM-powered scripture study features that go beyond surface-level summaries. It is citational, scholarly, and context-aware -- designed to deepen understanding rather than replace it.

Overview​

The AI assistant is available as both a sidebar widget and a dedicated pane. It operates in the context of whatever passage the user is currently reading, providing three primary capabilities:

CapabilityDescriptionEndpoint
Passage ExplanationScholarly, citational explanation of a scripture passagePOST /ai/explain
Study QuestionsAI-generated discussion and reflection questions for personal or group studyPOST /ai/questions
Cross-Reference SuggestionsAI-discovered connections between passages that may not exist in the manual cross-reference indexPOST /ai/connections

All AI responses include tappable citations that link back to specific passages and lexicon entries in the knowledge graph.

How It Works​

When a user asks the AI about a passage:

  1. The AI service receives the request with the current passage context
  2. It fetches the full passage data (text, cross-references, word alignments) from the content service
  3. Jinja2 prompt templates combine the passage context with the user's question
  4. The request goes to Anthropic Claude (primary) or OpenAI (fallback)
  5. The response is parsed, citations are linked to graph nodes, and the result is cached in Redis

Semantic Caching​

To minimize API costs, the AI service implements Redis-based semantic caching by prompt hash. If a similar question about the same passage has been asked recently, the cached response is returned without an LLM call. Cache TTL defaults to 3600 seconds (1 hour).

Access and Rate Limits​

AI features require the ai_features entitlement, available on Scholar and Academic plans:

PlanAI RequestsNotes
Reader (free)5/hourLimited taste of AI capabilities
Scholar50/hourFull access for personal study
Academic200/hourHigher limits for research workflows

Session-level counting tracks usage in Redis. When a user exhausts their hourly quota, the AI panel shows a clear message with the reset time rather than a generic error.

User Interface​

The core.ai plugin contributes a sidebar widget that provides quick access to AI features without leaving the reading flow. The widget shows a text input and preset prompt buttons ("Explain this passage", "What does the original language reveal?", "Generate study questions").

Dedicated Pane​

For deeper AI interaction, users can open the AI assistant as a full pane. The pane provides conversation history, longer responses, and the ability to ask follow-up questions in context.

Entry Points​

  • Cmd+Enter from any passage to ask the AI about the current selection
  • "Study This Verse" from the verse action sheet
  • Sidebar widget always accessible in the right dock zone
  • Hover card Layer 2 tab shows AI-generated insights for the hovered verse

Phased Rollout​

PhaseCapabilities
Phase 1 (current)Passage explanation, study questions, cross-reference suggestions
Phase 2Semantic search over graph embeddings, AI-guided exploration, personalized study plans
Phase 3Fine-tuned models on LDS scholarship corpus for higher-quality denominational responses

Deep Dive: Provider Abstraction​

The AI service uses an abstract LLMClient interface with concrete implementations for Anthropic and OpenAI. This allows:

  • Provider fallback -- If Anthropic is unavailable, requests automatically fall through to OpenAI
  • Model flexibility -- The Anthropic model is configurable via GOSPELIB_AI_ANTHROPIC_MODEL (defaults to claude-sonnet-4-20250514)
  • Cost optimization -- Different models can be used for different request types (e.g., a smaller model for study questions, a larger model for detailed explanations)

The service is implemented in Python with FastAPI at services/ai/, running on port 8400.