Scripture Search

Scripture Search is a hybrid C and Python search engine for exploring sacred texts through meaning, exact language, and direct references. The current collection contains 684 Bhagavad Gita source passages; the product and design system are structured to support additional religions, scriptures, translations, and languages later.

The interface is intentionally neutral and reading-first. It combines a warm editorial search experience with a quiet workspace structure so no tradition becomes the visual default for every future collection.

Highlights

• Semantic search powered by sentence-transformer embeddings
• Case-insensitive exact-text search
• Hybrid text and semantic ranking
• Constant-time passage lookup by numeric ID
• Save, copy, share, listen to, and find similar passages
• Responsive, keyboard-accessible reading interface
• C data structures for search and Python/Flask for the web API
• Windows development scripts and a tested Linux Docker deployment

Architecture

Browser
  └─ HTML, CSS, JavaScript
       └─ POST /api/search
            └─ Flask API
                 ├─ Python query enhancement and embeddings
                 └─ C search process
                      ├─ Hash table
                      ├─ Text search
                      ├─ Priority queue
                      └─ Binary passage database

The web wrapper generates a semantic query vector once and passes it to the C process. The standalone C application can still generate its own vector when used outside the web app.

Search modes

Mode	Purpose	Core approach
Meaning	Find conceptually related passages	Normalized vector similarity
Exact words	Find literal words or phrases	Case-insensitive text search
Hybrid	Require relevant language and rank by meaning	Text filtering plus vector ranking
Verse ID	Retrieve one known passage	Hash-table lookup

Run locally on Windows

Prerequisites

• Python 3.12
• GCC available on PATH

Setup

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r python\requirements.txt
.\REBUILD.bat
python web\app.py

Open http://127.0.0.1:5000.

The included SETUP_WEB.bat, REBUILD.bat, and START_WEB_APP.bat provide the same workflow for Command Prompt users.

API

Search

POST /api/search

{
  "query": "how can I face fear?",
  "search_type": "semantic",
  "limit": 5
}

Example response:

{
  "results": [
    {
      "id": 47,
      "chapter": 2,
      "verse_number": 9,
      "text": "Passage text",
      "score": 0.82
    }
  ],
  "count": 1,
  "query": "how can I face fear?",
  "search_type": "semantic"
}

Accepted search_type values are semantic, text, hybrid, and id.

Health check

GET /health

{"status": "ok"}

Docker deployment

The Docker image installs CPU-only PyTorch, compiles the C program for Linux, and serves Flask through Gunicorn.

docker build -t scripture-search .
docker run --rm -p 8080:8080 scripture-search

Open http://127.0.0.1:8080.

For a hosted container platform, deploy the repository with its Dockerfile and route traffic to the platform-provided PORT. The container command already reads that variable.

Model cold start

The first uncached semantic or hybrid request downloads the configured sentence-transformer model. A production environment therefore needs outbound access to Hugging Face, or the model cache should be baked into a private image. Text and ID searches do not require that download.

Repository layout

.
├── data/
│   ├── verses.txt          # Human-readable source collection
│   └── verses.bin          # Runtime passage database and vectors
├── python/
│   ├── embeddings.py       # Sentence-transformer interface
│   ├── query_embedder.py   # Query enhancement and vector cache
│   ├── search_api.py       # Python-to-C bridge
│   └── requirements.txt
├── src/
│   ├── advanced_search.c   # Interactive C entry point
│   ├── dsa.c / dsa.h       # Hash table and priority queue
│   ├── verse.c / verse.h   # Passage model and search algorithms
│   └── data/query loaders
├── web/
│   ├── app.py              # Flask API and static server
│   └── static/             # Browser interface
├── DESIGN.md               # Multi-faith visual language
└── Dockerfile

Generated query vectors, embedding caches, local executables, virtual environments, editor settings, and build output are deliberately excluded from Git. data/verses.bin remains versioned because it is required for runtime search.

Rebuild the passage database

When source passages change:

cd python
python data_loader.py
cd ..
.\REBUILD.bat

Database generation may download an embedding model and can take time on CPU.

Multi-faith roadmap

Future collections should add explicit metadata for tradition, scripture, book/chapter, passage type, language, translation, and source attribution. Collection-specific symbols and colors should remain scoped to that collection; the global navigation, search, result hierarchy, and actions should remain neutral and consistent.

See DESIGN.md for the visual and content-language principles.

Verification performed

• Python modules compile successfully
• Browser JavaScript passes syntax validation
• Flask index, static assets, health check, and empty-query validation pass
• Meaning, exact-text, hybrid, and ID searches return results
• Desktop and mobile layouts were inspected in Chromium
• The Linux Docker image builds successfully
• Gunicorn starts in the container and serves a real C-backed search request

Notes

• The semantic model is 768-dimensional; regenerated passage vectors must use a compatible model.
• Search caches are runtime artifacts and should not be committed.
• Sacred-text translations and licensing should be reviewed before adding or distributing new collections.