Bible Verse Decoder

A comprehensive Python script that parses, validates, and retrieves Bible verse references from natural language input, supporting multiple translation formats and flexible query patterns.

<role>You are a senior Python developer specializing in text parsing, regex pattern matching, and API integration for biblical text retrieval.</role>

<instructions>
Build a robust Bible Verse Decoder module that:
1. Accepts natural language input containing one or more verse references (e.g., "John 3:16", "Psalm 23:1-4", "Romans 8:28, Jeremiah 29:11")
2. Parses and validates each reference against canonical book names, chapter/verse ranges
3. Normalizes references to a standard format (Book Chapter:Verse[-Verse])
4. Fetches verse text from a configurable source (local JSON/CSV database or public API like Bible API)
5. Returns structured output with reference, verse text, translation metadata, and any parsing warnings
6. Handles edge cases: book abbreviations, chapter-only references, verse ranges, cross-chapter ranges, invalid references
7. Supports multiple translations via a [translation_code] parameter (default: "KJV")
8. Includes comprehensive error handling and logging
9. Provides a clean CLI interface and importable class for reuse
</instructions>

<context>
The decoder will be used in a [target_application] such as a sermon preparation tool, Bible study app, or devotional generator. Input comes from [input_source] (user text, file upload, chat message, etc.). The system must work offline with a bundled [bible_data_file] (JSON format: {book: {chapter: {verse: text}}}) and optionally online via [api_endpoint]. Performance target: parse and retrieve 50+ references in under [max_latency_ms] milliseconds.
</context>

<constraints>
- Use Python 3.9+ standard library only (requests allowed for API calls)
- No external NLP libraries; implement parsing with regex and string manipulation
- Canonical book list must include all 66 Protestant books with common abbreviations
- Validate chapter/verse bounds per book (e.g., Psalm 119 has 176 verses)
- Output format: JSON Lines (one JSON object per reference) or pretty-printed JSON
- Include type hints and docstrings for all public methods
- Write unit tests covering 90%+ of parsing logic using pytest
- Configuration via [config_file] (YAML) or environment variables
</constraints>

<format>
Deliverables:
1. `bible_decoder/` package with:
   - `__init__.py` (exports BibleDecoder class)
   - `parser.py` (reference parsing & validation)
   - `repository.py` (data access: local + API)
   - `models.py` (dataclasses: VerseRef, VerseText, DecodeResult)
   - `cli.py` (argument parsing, main entry point)
   - `config.yaml` (default configuration)
2. `tests/` with `test_parser.py`, `test_repository.py`, `test_integration.py`
3. `data/` with sample `bible_kjv.json` (minimum 5 books)
4. `README.md` with usage examples
5. `requirements.txt` (requests, pyyaml, pytest)
</format>

<tone>Professional, precise, and encouraging. Code should be production-ready, well-documented, and follow PEP 8 / PEP 257.</tone>

**Final Action:** Generate the complete project structure with all files. Start by creating the canonical book registry and regex parser in `parser.py`, then build outward. Verify with `pytest tests/ -v`.