# Bible-Companion - Project Context

> **For AI Assistant:** Read this file at the start of each session to understand project context and working specifications.

---

## Project Identity

**Project Name:** Bible-Companion
**Current Version:** 0.1.0 (Initial Scaffolding)
**Type:** Christological Conversational AI Service
**Platform:** FastAPI backend (Python) / Web API

**Purpose:** Interpret Scripture through the lens of Christ's incarnation, atonement, and resurrection. Provide conversational AI that helps users understand Scripture's redemptive narrative and Christ's uniqueness among world religions.

---

## Service Specifications (LOCKED)

### API Endpoint
- **Domain:** ai-bible.pikzulstudios.com/api/chat
- **Endpoint:** POST /api/chat
- **Protocol:** HTTP/HTTPS REST
- **Consumer:** Android Scripture app (natively rebuilt in Android Studio)

### Inference Configuration
- **Local Inference:** http://192.168.1.169:1234/v1 (LM Studio)
- **VPS Production Inference:** http://localhost:11434 (ollama)
- **Model:** LFM2.5 (llamafile/lfm2.5-1.2b, 1.2B parameters)
- **Model Type:** Lightweight, efficient for CPU/edge inference
- **Chat API:** OpenAI-compatible /v1/chat/completions

### Scripture Database
- **Translations:** KJV, NKJV, NIV, ESV, Message Redux (5 total)
- **Total Data:** ~20MB (all translations combined)
- **Embeddings:** all-MiniLM-L6-v2 (22MB, semantic verse search)
- **Persistence:** SQLite database (oracle.db)
- **Embedding Index:** In-memory SimpleEmbeddingIndex (cosine similarity search)

### Tool Use Approach
- **Method:** Prompt-based scripture reference detection (NOT structured function calling)
- **Pattern:** Regex extraction of Scripture references from LFM2.5 response
- **Regex Pattern:** `[A-Z0-9\s:]+\d+:\d+` (matches "John 3:16", "Romans 5:8-10", etc.)
- **Enrichment:** Automatic retrieval of all 5 translations + doctrinal context for detected references
- **Rationale:** Lightweight models (1.2B) unreliable with JSON function calling; prompt-based detection more reliable and controllable

### Theological Foundation (LOCKED IN)

**Hermeneutics:** Christological
- All Scripture testifies to Christ's person and work
- Old Testament interpreted through prophetic anticipation of Christ's coming
- New Testament reveals Christ's fulfillment and ongoing redemptive work

**Christ's Identity:**
- Alive, resurrected, redemptively active today
- Fully God and fully human (incarnational uniqueness)
- "I am" claims indicate eternal deity (not just teaching/prophet)
- Redemptive action-verb: not philosophical principle, but living relationship

**Love Definition:** Redemptive action, not sentiment
- Christ is love incarnate
- Love manifests as sacrifice, grace, transformation
- Agape (covenant redemption) vs. general affection

**Tone & Approach:**
- Loving and redemptive, not argumentative
- Focus on Christ's grace, resurrection, active presence
- Acknowledge complexity while remaining Gospel-centered
- Missional but humble (inviting, not condemning)

**Comparative Theology Awareness:**
- **Buddhism:** Enlightenment through self-effort; no incarnation, no external redemption
- **Islam:** Jesus as prophet, denies deity and bodily resurrection; incompatible with Incarnation theology
- **Stoicism:** Virtue through reason alone; differs from grace-based transformation
- **Key Contrast:** Christ is uniquely incarnational and redemptively alive (not philosophy, not past teacher, but present Savior)

---

## Technology Stack

### Backend
- **Framework:** FastAPI 0.104.1
- **Server:** Uvicorn 0.24.0
- **Language:** Python 3.8+
- **API Format:** OpenAI-compatible (supports both LM Studio and ollama)

### AI / ML Components
- **LLM:** LFM2.5 (1.2B parameters, lightweight, inference-optimized)
- **Embeddings:** sentence-transformers all-MiniLM-L6-v2 (22MB)
- **Inference Clients:** httpx (async HTTP)

### Data & Persistence
- **Database:** SQLite3
- **Schema:** Verses, Oracle Facts, Doctrinal Cross-References
- **Logging:** Conversations to JSONL for finetuning pipeline

### Dependencies
- fastapi 0.104.1
- uvicorn 0.24.0
- pydantic 2.5.0
- python-dotenv 1.0.0
- httpx 0.25.2
- sentence-transformers 2.2.2
- numpy 1.24.3
- torch 2.1.0

---

## Project Architecture

### Directory Structure
```
bible-companion/
├── main.py                 # FastAPI app, /api/chat endpoint, startup
├── models.py              # Pydantic schemas (ChatRequest, ChatResponse, etc.)
├── oracle_service.py      # Scripture Oracle class, semantic search, SQLite
├── llm_service.py         # LM Studio/ollama async inference client
├── requirements.txt       # Python dependencies
├── .env.local            # Local configuration (192.168.1.169:1234)
├── .env.example          # Configuration template
├── PROJECT_CONTEXT.md    # This file
├── data/                 # Data directory
│   ├── oracle.db         # SQLite database (verses, facts, xrefs)
│   └── conversations.jsonl  # Conversation logs (for finetuning)
└── models/               # (Reserved for future custom models/weights)
```

### Core Components

**FastAPI Application (main.py)**
- Entry point: uvicorn main:app
- Endpoints:
  - GET /health → Health check
  - POST /api/chat → Main chat endpoint
- Startup: Initialize Oracle, LM Client
- Middleware: CORS enabled for web consumers

**Request/Response Models (models.py)**
- ChatRequest: user message + conversation_id + options
- ChatResponse: ai response + enriched Scripture + metadata
- ScriptureReference, ScriptureVerse, EnrichedVerse classes
- Pydantic validation on all inputs

**Scripture Oracle (oracle_service.py)**
- SimpleEmbeddingIndex: In-memory cosine similarity search
- ScriptureOracle class:
  - Methods: add_verse(), add_doctrinal_fact(), retrieve_verses(), retrieve_verses_by_reference(), get_doctrinal_context()
  - SQLite schema: verses, oracle_facts, doctrinal_xrefs tables
  - Embedding storage: all-MiniLM-L6-v2 vectors
  - Startup: Load embeddings from DB into memory index for fast search

**LM Studio Client (llm_service.py)**
- Async HTTP client for OpenAI-compatible API
- Methods: generate(), health_check()
- Supports both LM Studio (local) and ollama (VPS)
- Timeout handling, error logging

### Request Workflow
```
User Message
    ↓
ChatRequest (Pydantic validation)
    ↓
Oracle: Semantic verse search (user query → embedding → cosine search)
    ↓
System Prompt: Augment with retrieved verses + doctrinal context
    ↓
LFM2.5 Inference: Generate response with system prompt + user message
    ↓
Scripture Reference Extraction: Regex parse response for citations
    ↓
Oracle: Retrieve all 5 translations + doctrinal context for each reference
    ↓
Response Enrichment: Embed citations with metadata
    ↓
Conversation Logging: Write to data/conversations.jsonl
    ↓
ChatResponse (JSON with enriched verses)
```

---

## Working Preferences

### Communication Style
- Direct, action-oriented implementation
- Concise responses (no verbose explanations)
- Proactive (infer intent, don't ask permission)
- No tool name announcements

### Code Style
- Use multi_replace_string_in_file for multiple edits
- Include 3-5 lines context before/after replacements
- Clear variable names (no abbreviations)
- Docstring on all functions (Google-style)
- Type hints on all function signatures
- Logging calls for significant operations (INFO level)

### Git Workflow
- Frequent commits with descriptive messages (bullet points)
- Track all scaffold files + configuration
- Include requirements.txt with exact versions

---

## Current Features (v0.1.0)

### Implemented
- ✅ FastAPI app structure with /health + /api/chat endpoints
- ✅ Pydantic request/response validation
- ✅ Oracle architecture (SQLite + SimpleEmbeddingIndex + cosine similarity)
- ✅ LM Studio/ollama async inference client (OpenAI-compatible)
- ✅ Scripture reference regex detection
- ✅ Conversation logging to JSONL
- ✅ Configuration via .env files
- ✅ Christological system prompt template

### In Progress
- 🔄 Load 5 Bible translations into Oracle DB
- 🔄 Seed Oracle with Christological doctrinal facts
- 🔄 Test /api/chat endpoint locally with LM Studio
- 🔄 Verify scripture enrichment workflow end-to-end

### Planned (Phase 2+)
- 📋 VPS deployment (systemd service, ollama on production)
- 📋 Finetuning pipeline (collect conversations, identify patterns)
- 📋 Web UI for testing (simple chat interface)
- 📋 Advanced doctrinal retrieval (doctrine types, confidence scoring)
- 📋 Multi-turn conversation context management
- 📋 Rate limiting + usage tracking

---

## Bootstrap Plan (Next Steps)

### Step 1: Load Scripture Translations
1. Locate KJV, NKJV, NIV, ESV, Message Redux (JSON or text format)
   - Check bible-ai/data-osis/ for existing data
   - If not found, download from biblestudytools.com or similar
2. Parse translation files and extract:
   - Book + chapter + verse number
   - Verse text
   - Translation name
3. Populate oracle.db via oracle_service.add_verse()
4. Trigger embedding generation (all-MiniLM-L6-v2)
5. Verify embeddings loaded into in-memory SimpleEmbeddingIndex

### Step 2: Seed Doctrinal Facts
1. Add core Christological facts to oracle_facts table:
   - Jesus is Lord, fully God and fully human
   - Incarnation, atonement, resurrection are Scripture's core
   - OT testifies to Christ; NT reveals His fulfillment
   - Christ is alive, interceding, continuing His work
   - Love is redemptive action (agape, not sentiment)
2. Add comparative theology facts:
   - Buddhism teaching vs. Incarnation uniqueness
   - Islam's denial of deity/resurrection
   - Stoicism vs. grace-based transformation
3. Add OT→NT fulfillment cross-references:
   - Isaiah 53 → Atonement
   - Genesis 3:15 → Gospel promise
   - Psalms 22, 69, 110 → Christ's passion + exaltation
   - Psalm 110:1 → Exaltation
   - Daniel 7:13-14 → Second coming

### Step 3: Local Testing
1. Start LM Studio at http://192.168.1.169:1234/v1
2. Activate Python venv: python -m venv .venv && .\.venv\Scripts\activate
3. Install dependencies: pip install -r requirements.txt
4. Start FastAPI: uvicorn main:app --reload
5. Test endpoint: POST http://localhost:8000/api/chat
   ```json
   {"message": "What does Scripture teach about redemption?"}
   ```
6. Verify response includes Scripture references + enriched verses
7. Check data/conversations.jsonl for logged conversation

### Step 4: VPS Deployment (Production)
1. Copy bible-companion/ to VPS
2. Install ollama on VPS: ollama pull llama/lfm2.5-1.2b
3. Create systemd service: /etc/systemd/system/bible-companion.service
4. Configure nginx reverse proxy: ai-bible.pikzulstudios.com → localhost:8000
5. Enable HTTPS: certbot + Let's Encrypt
6. Test: curl https://ai-bible.pikzulstudios.com/api/chat

---

## Known Issues / Gotchas

- **LFM2.5 Inference Speed:** 1.2B model is lightweight but slower than larger models. Expect 2-5s per response on CPU.
- **Embedding Startup:** First load of all-MiniLM-L6-v2 will download model (~22MB) if not cached.
- **SQLite Concurrent Writes:** Keep conversation logging single-threaded or use WAL mode.
- **Regex Precision:** Scripture reference regex may match false positives (e.g., "1 John 1:1" vs "1 Corinthians 1:1"). Refine pattern if needed.
- **Doctrine Fallback:** If Oracle has no matching doctrinal context, response still works (graceful degradation).

---

## Quick Reference

**Install dependencies:**
```bash
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
```

**Run locally:**
```bash
uvicorn main:app --reload
# API at http://localhost:8000
# Docs at http://localhost:8000/docs
```

**Test chat endpoint:**
```bash
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the Gospel?"}'
```

**View conversation logs:**
```bash
cat data/conversations.jsonl | python -m json.tool
```

---

## Related Projects

- **scripture-for-my-situation** → Android app being rebuilt natively in Android Studio
- **echo** → Sibling AI service (mature Oracle pattern adapted here)
- **bible-ai** → Legacy Flask backend (superseded by bible-companion)

---

**Last Updated:** January 12, 2026
**Status:** Initial scaffolding complete, awaiting Scripture data loading
**Next Major Milestone:** Local testing with LM Studio + Scripture enrichment verification