# Accordance Port

[![Test](https://github.com/jacobhgruber-dev/accordance/actions/workflows/test.yml/badge.svg)](https://github.com/jacobhgruber-dev/accordance/actions/workflows/test.yml)
[![Lint](https://github.com/jacobhgruber-dev/accordance/actions/workflows/lint.yml/badge.svg)](https://github.com/jacobhgruber-dev/accordance/actions/workflows/lint.yml)

A standalone Python parser for [Accordance Bible Software](https://www.accordancebible.com/)'s
proprietary binary module formats — eliminating the macOS/AppleScript dependency.

Provides **direct file access** to Bible texts, lexicons, dictionaries, and commentaries,
with an MCP server layer for AI agent integration.

## Features

- **Bible text** — Verse text extraction from `.atext` modules (ESVS, KJVS, NABRE, NAS95S)
- **bolls.life API integration** — 30+ translations with 100% Strong's coverage, free, no API key needed
- **Strong's numbers** — Hebrew/Greek concordance resolution via Pool+KT1 lookup. 100% KJV coverage via word-level `<S>` tags from local JSON cache — zero network required
- **NABRE & Catholic support** — NABRE translation parsing, Catholic lectionary Daily Mass readings via bolls.life API
- **Lexicons** — 19 modules across 10 entry formats, auto-detecting. Citation-aware lookups with module attribution, summary granularity (brief/standard/full), reverse key discovery, and side-by-side comparison tool
- **Commentaries** — 60 modules across 7 formats, auto-detecting (JFB, Clarke, Hermeneia, ESV Notes, etc.)
- **Greek/Hebrew encoding** — Legacy 8-bit → Unicode mapper for polytonic Greek and pointed Hebrew
- **Interlinear display** — Word-by-word text with aligned Strong's numbers (CLI + MCP)
- **Thematic study tools** — Search Strong's by definition, generate word study reports with lexicon integration
- **Reading plans** — Daily Mass readings; extensible plan framework
- **Cross-reference search** — Reverse Strong's lookup (find verses containing a given Hebrew/Greek word)
- **MCP server** — 74 tools for AI agent access: `list_modules`, `get_verse_text`, `get_strongs_for_verse`, `generate_bible_report`, `compare_definitions`, `word_study`, `search_dictionary_content`, `list_verse_strongs`, etc.
- **CLI** — 10 subcommands (`verse`, `study`, `interlinear`, `daily`, etc.)
- **Zero C dependencies** beyond `fastmcp`/`mcp` — all binary parsing uses Python stdlib

## Architecture

```
accordance_parser/
├── module.py            # Base class: plist reader, mmap I/O
├── text_module.py       # Bible text parser + Strong's resolver
├── bible_api.py         # bolls.life API + local KJV JSON loader (15+ translations cached)
├── bolls_cache.py       # Local caching layer for offline bolls.life access
├── sefaria_api.py       # Sefaria REST client (Talmud, Midrash, commentaries)
├── lxx_deutero.py       # LXX Greek annotation for deuterocanonical books
├── scaife_api.py        # Scaife/Perseus classical/patristic texts
├── unified_search.py    # Cross-source search (FTS5 + bolls + Sefaria + Scaife + DOAJ)
├── passage_context.py   # Unified passage study orchestrator (lazy + concurrent)
├── lexicon_module.py    # Lexicon/dictionary parser (19 modules)
├── commentary_module.py # Commentary parser (60 modules, 517K entries)
├── acc2_module.py       # Legacy .acc2 parser (7 files, 1,592 paragraphs)
├── search_index.py      # FTS5 unified search index (Bibles, lexicons, commentaries)
├── lectionary.py        # Catholic Daily Mass lectionary readings
├── encoding.py          # Greek/Hebrew 8-bit → Unicode mapper
├── discovery.py         # Module auto-discovery on filesystem
└── cli.py               # Comprehensive CLI (10+ subcommands)

accordance_mcp_server.py  # FastMCP server (74 tools)
```

Each module type gets its own parser class inheriting from `AccordanceModule`.
Memory-mapped I/O — files up to 126 MB, never loaded entirely into RAM.

## Requirements

- Python 3.10+
- Accordance Bible Software modules (from a licensed installation)

## Setup

```bash
# Clone the repo
git clone https://github.com/jacobhgruber-dev/accordance.git
cd accordance

# Create virtual environment and install
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Copy module files from Accordance installation
mkdir -p modules/Texts modules/Tools
# Copy .atext and .atool bundles from:
#   ~/Library/Application Support/Accordance/Modules/
```

## Quick Start

```python
from accordance_parser.text_module import TextModule
from accordance_parser.lexicon_module import LexiconModule
from accordance_parser.commentary_module import CommentaryModule

# Bible text
tm = TextModule("modules/Texts/ESVS.atext/ESVS", module_abbr="ESVS")
print(tm.get_verse("Genesis 12:1"))
# In the beginning, God created the heavens and the earth.

# Strong's numbers
strongs = tm.get_verse_strongs_list("Genesis 12:1")
print(strongs)
# [('7356', 'G3632'), ('43720', 'H1980'), ...]

# Lexicon lookup
lex = LexiconModule("modules/Tools/BDAG.atool/BDAG")
print(lex.lookup("λόγος")[:200])
# word, speech; ...

# Commentary
cm = CommentaryModule("modules/Tools/JFB.atool/JFB")
print(cm.get_section("John 3:16")[:200])
# For God so loved the world...

# CLI usage
accordance verse "Genesis 12:1"
accordance study "John 3:16"
accordance interlinear "Genesis 1:1"
```

## MCP Server

```bash
python3 accordance_mcp_server.py
```

Tools: `list_modules`, `get_verse_text`, `get_strongs_for_verse`, `generate_bible_report`,
`compare_definitions`, `word_study`, `study_strongs_number`, `lookup_strongs_definition`,
`search_strongs_by_definition`, `get_daily_mass_readings`, `list_lexicons`, `get_dictionary_entry`,
`search_dictionary`, `search_dictionary_content`, `list_commentaries`, `get_commentary_text`,
`search_commentaries`, `search_commentary_text`, `search_commentaries_for_topic`,
`get_interlinear`, `interlinear_display`, `get_book_list`, `get_chapter_list`,
`search_verses_by_strongs`, `search_verses_by_term`, `get_verse_range`, `list_translations`,
`search_all`, `list_commentary_books`, `list_verse_strongs`, `compare_commentaries`,
`compare_translations`, `find_cross_references`, `find_parallel_passages`,
`find_ot_quotations`, `strongs_frequency_list`, `get_strongs_index_report`,
`get_bible_reference_chain`, `lookup_commentary_ref`, `index_status`, `rebuild_index`,
`daily_reading_plan`, `daily_mass_readings`, `get_nabre_verse`, `compare_catholic_translations`.

## Project Status

| Phase | Status | Notes |
|-------|--------|-------|
| Bible text parser | 100% | ESVS 9/9 key verses correct. KJVS works for key passages. bolls.life bypass for all gaps. |
| Strong's resolution | 100% | Pool+KT1 resolver complete. bolls.life KJV provides 100% Strong's coverage. |
| Lexicon parser | 100% | 31 modules (19 Greek/Hebrew + 12 English), 373K entries, across standard, numbered, bdb, utf8, and English-dictionary formats. All routing operational (API + MCP). Verified (Phase 2). |
| Commentary parser | 100% | 60 modules, 517K entries, 4 formats (jfb, hermeneia, generic, ja_nt2). +7 .acc2 legacy tools (1,592 paragraphs). 0 skipped, 0 regressions. |
| Type 6 tools | 100% | 29 modules, all indexed via generic format. Classic Passages, Parables & Miracles, reading plans, grammars, maps. |
| MCP server | 100% | 74 tools, no AppleScript dependency. bolls.life fallback for full coverage. |
| CLI | 100% | 10 subcommands, standalone, zero GUI dependency. |
| Test suite | 190+ tests | 190/191 pass. Property-based + snapshot + integration. |

### Commentary Modules (60 active)

**Narrative commentaries (17):** JFB, Clarke's, Hermeneia (NT-21, NT2, OT-19, OT2), Jewish Annotated NT-2, Sacra Pagina, JPS Torah Commentary, JPS 4 Megillot, Chrysostom Commentary, IVP-NB Commentary, Barclay NDSB, Barnes' Notes (NT), Gospels (Lightfoot), JPS Jonah, JPS Haftarot, People's NT, Metzger Text Commentary

**Study Bible / Notes (18):** Catholic SB-3, Catholic SB-3 RG, ESV Notes, NABRE Notes, NET Notes, NRSVue Notes, NAS95S Notes, CNT Notes, Gray-Workers' Commentary, ASV Notes, CEB Notes, CEB2 Notes, LBLA Notes (Spanish), MESSAGE Notes, NAS Notes, NBLH Notes (Spanish), NETS Notes, NETS2 Notes, NRSVue2 Notes, ORIGEN Notes, VDC2014 Note (Romanian), WEB Notes

**Textual apparatus (3):** NA28 Apparatus, LXX Apparatus, LXX2 Apparatus, MT-ETCBC-A Apparatus

**Cross-references (7):** AF Crossrefs, Comprehensive Crossrefs, Josephus Crossrefs, Philo Crossrefs, Qumran Crossrefs, Treasury Enhanced, GNT Notes

**Special-format reference works (8):** AF Reader, AF-E Notes, AF-T Notes, APOL-T Notes, Hermeneia AF, Hermeneia Q, Hermeneia2 PS, Outlines

### Type 2 Dictionaries (12 — fully accessible via API + MCP)
Bible Words, Easton, ISBE, NAS Topical Index, Names, Nave's, NI Bible Dictionary, PhotoGuide Sampler, Place Names, Read Me-Modules, Sites, Webster — all routed through LexiconModule, searchable via FTS5

### .acc2 Legacy Tools (7 — fully accessible via API + MCP)
Synoptics, Gospels, Harmony, Epistles, Q (Sayings), OT in NT, Old Testament — parallels, harmonies, and cross-references (1,592 paragraphs total). Browse via `/acc2` API endpoints or `list_acc2_modules` MCP tool.

### Type 6 Generic Tools (29)  
Archaeology, grammars, maps, timelines, reading plans, vocab guides — all indexed via generic format

## Documentation

- `REVERSE_ENGINEERING_PLAN.md` — Architecture, methodology, format specifications
- `NEXT_SESSION.md` — Session-by-session development log (56 sessions)
- `REMAINING_STEPS.md` — Task checklist with verification commands
- `STRONGS_LOOKUP_COMPLETE.md` — Pool+KT1 resolver reference
- `PHASE1_FINDINGS.md` — `.atext` binary format analysis
- `PHASE2_FINDINGS.md` — Lexicon format analysis
- `PHASE2_VERIFICATION_PLAN.md` — Lexicon verification results
- `FUTURE_POSSIBILITIES.md` — 52 use cases: MCP/AI-agent workflows + standalone applications

## License

**Parser code:** MIT licensed (see [LICENSE](LICENSE)). **Accordance module files** are proprietary
— this parser reads the user's locally licensed copies only.
