Getting Started

Prerequisites

• Python 3.12

• Node.js 22

• Docker and Docker Compose

• pnpm (Node package manager)

• Poetry (Python dependency manager)

Environment Setup

Copy and configure the environment file:

cp .env.example .env
# Set: NVIDIA_API_KEY, GENERATION_MODEL, EMBEDDING_MODEL, etc.

All model names and API keys are configured via environment variables – nothing is hardcoded.

Database and Seed Data

Start the database:

docker compose up db -d

Install backend dependencies, run migrations, and load the seed data (701 verses + translations):

cd backend
poetry install
poetry run python manage.py migrate
poetry run python manage.py load_seed

Load Opus enrichments and generate embeddings:

poetry run python manage.py load_enrichments

Running the Backend

cd backend
poetry run python manage.py runserver 0.0.0.0:8000

Running the Frontend

cd frontend
pnpm install
pnpm dev

The Vite dev server is available at http://localhost:5173. In production, Caddy proxies to the built SvelteKit app on port 3000.

Running Tests

Backend:

cd backend
DATABASE_URL="sqlite:///test.db" poetry run pytest
poetry run ruff check .

Frontend:

cd frontend
pnpm install
pnpm test        # vitest
pnpm check       # TypeScript check