software/src/context/builder.py

1"""Context builder for translation prompts."""23from __future__ import annotations45from src.context.glossary import GlossaryManager6from src.context.pericope import PericopeManager7from src.data.loader import DataLoader8from src.models.pericope import ChunkTranslationContext, Pericope9from src.models.verse import TranslationContext, Verse, VerseReference101112class ContextBuilder:13    """Builds translation context for verses and chunks."""1415    def __init__(16        self,17        loader: DataLoader,18        glossary: GlossaryManager,19        context_window: int = 3,20        pericope_manager: PericopeManager | None = None,21    ) -> None:22        """Initialize the context builder.2324        Args:25            loader: Data loader for source texts.26            glossary: Glossary manager for theological terms.27            context_window: Number of verses before/after to include.28            pericope_manager: Optional pericope manager for chunk translation.29        """30        self.loader = loader31        self.glossary = glossary32        self.context_window = context_window33        self.pericope_manager = pericope_manager or PericopeManager()3435    def build_context(self, reference: VerseReference) -> TranslationContext:36        """Build full translation context for a verse.3738        Args:39            reference: The verse reference to build context for.4041        Returns:42            TranslationContext with all available context.43        """44        # Load the target verse45        target_verse = self.loader.load_verse(reference)4647        # Load surrounding verses48        preceding = self._get_preceding_verses(reference)49        following = self._get_following_verses(reference)5051        # Load chapter summary52        chapter_summary = self.loader.load_chapter_summary(53            reference.book, reference.chapter54        )5556        # Load book metadata57        book_metadata = self.loader.load_book_metadata(reference.book)5859        # Find relevant glossary terms from the source text60        glossary_terms = self._find_relevant_terms(target_verse)6162        return TranslationContext(63            target_verse=target_verse,64            preceding_verses=preceding,65            following_verses=following,66            chapter_summary=chapter_summary,67            book_metadata=book_metadata,68            glossary_terms=glossary_terms,69        )7071    def _get_preceding_verses(self, reference: VerseReference) -> list[Verse]:72        """Get verses preceding the target verse."""73        verses = []74        book = reference.book75        chapter = reference.chapter76        verse_num = reference.verse7778        for i in range(self.context_window, 0, -1):79            target_verse = verse_num - i80            if target_verse >= 1:81                ref = VerseReference(book=book, chapter=chapter, verse=target_verse)82                verse = self.loader.load_verse(ref)83                # Only include if verse has content84                if verse.has_source_text() or verse.english_kjv:85                    verses.append(verse)8687        return verses8889    def _get_following_verses(self, reference: VerseReference) -> list[Verse]:90        """Get verses following the target verse."""91        verses = []92        book = reference.book93        chapter = reference.chapter94        verse_num = reference.verse9596        for i in range(1, self.context_window + 1):97            target_verse = verse_num + i98            ref = VerseReference(book=book, chapter=chapter, verse=target_verse)99            verse = self.loader.load_verse(ref)100            # Only include if verse has content101            if verse.has_source_text() or verse.english_kjv:102                verses.append(verse)103104        return verses105106    def _find_relevant_terms(self, verse: Verse) -> list:107        """Find glossary terms relevant to a verse."""108        terms = []109110        # Search in Greek text111        if verse.greek_text:112            terms.extend(self.glossary.find_terms_in_text(verse.greek_text))113114        # Search in Greek transliteration115        if verse.greek_translit:116            for term in self.glossary.find_terms_in_text(verse.greek_translit):117                if term not in terms:118                    terms.append(term)119120        # Search in Hebrew text121        if verse.hebrew_text:122            for term in self.glossary.find_terms_in_text(verse.hebrew_text):123                if term not in terms:124                    terms.append(term)125126        return terms127128    def build_chunk_context(129        self, book: str, pericope: Pericope130    ) -> ChunkTranslationContext:131        """Build full translation context for a pericope/chunk.132133        Args:134            book: Book name.135            pericope: The pericope to build context for.136137        Returns:138            ChunkTranslationContext with all available context.139        """140        # Load all verses in the pericope141        verses = []142        for verse_ref in pericope.verses:143            chapter, verse_num = map(int, verse_ref.split(":"))144            ref = VerseReference(book=book, chapter=chapter, verse=verse_num)145            verse = self.loader.load_verse(ref)146            verses.append(verse)147148        # Load preceding context (verses before first verse)149        preceding = self._get_chunk_preceding_verses(book, pericope)150151        # Load following context (verses after last verse)152        following = self._get_chunk_following_verses(book, pericope)153154        # Load chapter summary (use first chapter)155        chapter_summary = self.loader.load_chapter_summary(156            book, pericope.start_chapter157        )158159        # Load book metadata160        book_metadata = self.loader.load_book_metadata(book)161162        # Find glossary terms from all verses163        glossary_terms = self._find_chunk_terms(verses)164165        return ChunkTranslationContext(166            pericope=pericope,167            book=book,168            verses=verses,169            preceding_verses=preceding,170            following_verses=following,171            chapter_summary=chapter_summary,172            book_metadata=book_metadata,173            glossary_terms=glossary_terms,174        )175176    def build_chunk_context_by_id(177        self, pericope_id: str178    ) -> ChunkTranslationContext | None:179        """Build chunk context by pericope ID.180181        Args:182            pericope_id: The pericope identifier.183184        Returns:185            ChunkTranslationContext or None if pericope not found.186        """187        result = self.pericope_manager.get_pericope_by_id(pericope_id)188        if result is None:189            return None190191        book, pericope = result192        return self.build_chunk_context(book, pericope)193194    def build_chunk_context_for_verse(195        self, reference: VerseReference196    ) -> ChunkTranslationContext | None:197        """Build chunk context for the pericope containing a verse.198199        Args:200            reference: Verse reference.201202        Returns:203            ChunkTranslationContext or None if no pericope found.204        """205        pericope = self.pericope_manager.get_pericope(206            reference.book, reference.chapter, reference.verse207        )208        if pericope is None:209            return None210211        return self.build_chunk_context(reference.book, pericope)212213    def _get_chunk_preceding_verses(214        self, book: str, pericope: Pericope215    ) -> list[Verse]:216        """Get verses preceding the pericope for context."""217        verses = []218        chapter = pericope.start_chapter219        verse_num = pericope.start_verse220221        for i in range(self.context_window, 0, -1):222            target_verse = verse_num - i223            if target_verse >= 1:224                ref = VerseReference(book=book, chapter=chapter, verse=target_verse)225                verse = self.loader.load_verse(ref)226                if verse.has_source_text() or verse.english_kjv:227                    verses.append(verse)228229        return verses230231    def _get_chunk_following_verses(232        self, book: str, pericope: Pericope233    ) -> list[Verse]:234        """Get verses following the pericope for context."""235        verses = []236        chapter = pericope.end_chapter237        verse_num = pericope.end_verse238239        for i in range(1, self.context_window + 1):240            target_verse = verse_num + i241            ref = VerseReference(book=book, chapter=chapter, verse=target_verse)242            verse = self.loader.load_verse(ref)243            if verse.has_source_text() or verse.english_kjv:244                verses.append(verse)245246        return verses247248    def _find_chunk_terms(self, verses: list[Verse]) -> list:249        """Find glossary terms relevant to all verses in a chunk."""250        terms = []251        seen = set()252253        for verse in verses:254            verse_terms = self._find_relevant_terms(verse)255            for term in verse_terms:256                if term.original not in seen:257                    terms.append(term)258                    seen.add(term.original)259260        return terms261