AI Service

The AI service provides LLM-powered scripture study features — passage explanations, study questions, and cross-reference suggestions. It uses Anthropic as the primary LLM provider with OpenAI as a fallback, and caches responses in Redis to minimize API costs.

Quick Reference

Property	Value
Port	8400
Language	Python 3.12
Framework	FastAPI + Uvicorn
Package	gospelib_ai
Entry point	src/gospelib_ai/main.py → create_app()
Primary LLM	Anthropic (Claude)
Fallback LLM	OpenAI
Cache	Redis (port 6380)

Responsibilities

• Passage explanation — Scholarly, citational explanations of scripture passages
• Study questions — AI-generated discussion and reflection questions
• Cross-reference suggestions — AI-discovered connections between passages
• Semantic caching — Avoids redundant LLM calls for similar prompts

Phased Rollout

Phase	Capabilities
Phase 1 (current)	Basic passage explanation, study questions, cross-reference suggestions
Phase 2	Semantic search over graph (embeddings), AI-guided exploration, personalized study plans
Phase 3	Fine-tuned models on LDS scholarship corpus

Running Locally

cd services/ai
uv sync
uv run uvicorn gospelib_ai.main:create_app --factory --reload --port 8400

The service requires an Anthropic API key and Redis to be running.

Environment Variables

Variable	Default	Description
GOSPELIB_AI_PORT	8400	HTTP listen port
GOSPELIB_AI_ANTHROPIC_API_KEY	—	Anthropic API key (required)
GOSPELIB_AI_OPENAI_API_KEY	—	OpenAI API key (fallback)
GOSPELIB_AI_ANTHROPIC_MODEL	claude-sonnet-4-20250514	Anthropic model name
GOSPELIB_AI_REDIS_URL	redis://localhost:6380	Redis for response caching
GOSPELIB_AI_CACHE_TTL	3600	Default cache TTL (seconds)
GOSPELIB_AI_CONTENT_SERVICE_URL	http://localhost:8100	Content service for passage context
GOSPELIB_AI_DEBUG	false	Enable debug mode

Health Check

curl http://localhost:8400/health
# {"status": "ok"}

Application Factory

# services/ai/src/gospelib_ai/main.py
def create_app() -> FastAPI:
    app = FastAPI(
        title="GospeLib AI API",
        version="1.0.0",
        docs_url="/docs" if settings.debug else None,
    )

    app.include_router(explain.router,     prefix="/explain",     tags=["explain"])
    app.include_router(questions.router,   prefix="/questions",   tags=["questions"])
    app.include_router(connections.router, prefix="/connections", tags=["connections"])

    return app

Configuration

# services/ai/src/gospelib_ai/config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    port: int = 8400
    anthropic_api_key: str
    openai_api_key: str = ""
    anthropic_model: str = "claude-sonnet-4-20250514"
    redis_url: str = "redis://localhost:6380"
    cache_ttl: int = 3600
    content_service_url: str = "http://localhost:8100"
    debug: bool = False

    class Config:
        env_prefix = "GOSPELIB_AI_"

Plan-Gated

All AI endpoints require the ai_features entitlement, available on Scholar and Academic plans. Free-tier users get 5 AI requests per hour.

Docker

FROM python:3.12-slim AS builder
WORKDIR /app
RUN pip install uv
COPY pyproject.toml ./
RUN uv sync --no-dev
COPY src/ ./src/

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /app /app
EXPOSE 8400
CMD ["uvicorn", "gospelib_ai.main:create_app", "--factory", "--host", "0.0.0.0", "--port", "8400"]

Related Pages

• LLM Client Architecture — provider abstraction and caching decorator
• Prompt Templates — Jinja2 template system
• Content Service — passage data consumed by AI features