biblia 0.8.0

Biblical study assistant with AI-powered analysis and research

Biblia

A terminal-based biblical research assistant. Generates theological analysis, daily verse devotionals, spiritual reflections, and exportable study sessions — powered by Google Gemini 2.5 Flash.

---

Installation

From PyPI

pip install biblia

From source

git clone https://github.com/ashioyajotham/bible.git
cd bible
pip install -e .

Runtime dependencies: google-generativeai, rich, requests, python-dotenv, colorama. No GPU, no PyTorch, no HuggingFace stack required.

---

Configuration

Create a .env file in your working directory:

GEMINI_API_KEY=your_gemini_key
SERPER_API_KEY=your_serper_key   # web search for teaching enrichment
ESV_API_KEY=your_esv_key         # verse text lookup

All three keys are validated on first run; missing values are prompted interactively and can be saved to .env.

---

Usage

bible [--theme dark|scholar|minimal] [--verbose]

Command	Alias	Description
teach	t	Generate theological analysis on any topic
verse	v	Fetch a daily verse with AI-generated devotional
reflect	r	Summarise and reflect on the current session
export	e	Write the full session to a Markdown file
help	h	Show command reference
exit	q	Quit

Theme options

Theme	Character
dark	Cyan/blue accents — default terminal look
scholar	Amber/yellow tones — warm, document-like
minimal	White borders only — maximum readability

---

Architecture

bible/
├── agent/
│   ├── bible_agent.py       — main agent; owns the command dispatch loop
│   ├── search_agent.py      — Serper + Gemini search-and-analyse pipeline
│   ├── base_agent.py        — abstract agent with goal/planner/memory stubs
│   └── components/
│       ├── session.py       — StudySession: accumulates teachings/verses/reflections
│       ├── goal_system.py
│       ├── planner.py
│       ├── memory.py
│       └── learner.py
├── services/
│   ├── model_manager.py     — singleton GeminiLLM factory
│   ├── serper_service.py    — Serper search API wrapper
│   └── llm/
│       ├── gemini_llm.py    — Gemini 2.5-flash wrapper
│       ├── model_selector.py
│       └── model_types.py
├── utils/formatters/
│   ├── console_formatter.py — Rich-based TUI renderer; theme-aware
│   └── markdown_formatter.py
├── config/settings.py       — env-based Config dataclass
├── models/
│   ├── verse.py
│   └── verse_categories.py
├── tests/
│   ├── conftest.py
│   ├── test_bible_agent.py  — unit tests
│   └── test_integration.py  — end-to-end flow tests
└── main.py                  — CLI entry point

---

Running tests

pip install pytest
pytest

Integration tests mock all external APIs (Gemini, Serper, ESV) so no keys are needed to run the suite.

---

Publishing (maintainers)

This repo uses OIDC trusted publishing to PyPI — no PYPI_API_TOKEN secret is needed.

One-time setup on pypi.org:

1. Go to your project → Publishing → Add a trusted publisher.
2. Enter: owner ashioyajotham, repository bible, workflow publish.yml.

After that, creating a GitHub release triggers the workflow automatically.

---

License

MIT — see LICENSE.

---

Disclaimer

Biblia is a research and study aid. Output should be cross-referenced with authoritative theological sources and pastoral guidance.