refactor(ebook-search): simplify search and phrase matching

python/ebook_search/protected_phrases/models.py

@@ -8,6 +8,8 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from collections.abc import Mapping
 
+    from python.orm.richie import EbookProtectedPhrase
+
 
 @dataclass(slots=True)
 class PhraseCandidate:
@@ -71,47 +73,24 @@ class LLMJudgment:
 
 @dataclass(frozen=True, slots=True)
 class PhraseLookup:
-    """In-memory lookup maps used for constant-time phrase-window checks.
+    """In-memory phrase metadata used for constant-time text-window checks.
 
     Attributes:
-        norm_to_phrase_ids (Mapping[str, tuple[int, ...]]): Normalized phrase to protected phrase ids.
-        alias_to_phrase_ids (Mapping[str, tuple[int, ...]]): Normalized alias to protected phrase ids.
+        phrase_ids_by_norm (Mapping[str, tuple[int, ...]]): Canonical and alias norms to phrase ids.
+        phrases_by_id (Mapping[int, EbookProtectedPhrase]): Protected phrase metadata by id.
         min_tokens (int): Smallest token-window size to test.
         max_tokens (int): Largest token-window size to test.
     """
 
-    norm_to_phrase_ids: Mapping[str, tuple[int, ...]]
-    alias_to_phrase_ids: Mapping[str, tuple[int, ...]]
+    phrase_ids_by_norm: Mapping[str, tuple[int, ...]]
+    phrases_by_id: Mapping[int, EbookProtectedPhrase]
     min_tokens: int
     max_tokens: int
 
 
 @dataclass(frozen=True, slots=True)
 class PhraseMatch:
-    """An unhydrated query or chunk phrase match.
-
-    Attributes:
-        phrase_norm (str): Normalized text of the matched window.
-        start_token (int): Index of the first matched token.
-        end_token (int): Index one past the last matched token.
-        token_count (int): Number of tokens in the match.
-        phrase_id (int | None): Matched protected phrase id when known.
-        start_char (int | None): Start character offset in the source text.
-        end_char (int | None): End character offset in the source text.
-    """
-
-    phrase_norm: str
-    start_token: int
-    end_token: int
-    token_count: int
-    phrase_id: int | None = None
-    start_char: int | None = None
-    end_char: int | None = None
-
-
-@dataclass(frozen=True, slots=True)
-class HydratedPhraseMatch:
-    """A phrase match with protected-phrase metadata attached.
+    """A detected phrase match with protected-phrase metadata attached.
 
     Attributes:
         phrase_id (int): Protected phrase id.
@@ -152,21 +131,6 @@ class HydratedPhraseMatch:
     series_id: int | None = None
 
 
-@dataclass(frozen=True, slots=True)
-class ChunkPhraseHit:
-    """One protected phrase with its mention count inside one retrieved chunk.
-
-    Attributes:
-        phrase_id (int): Protected phrase id.
-        phrase_text (str): Display text of the protected phrase.
-        mention_count (int): Indexed mentions of the phrase in the chunk.
-    """
-
-    phrase_id: int
-    phrase_text: str
-    mention_count: int
-
-
 @dataclass(frozen=True, slots=True)
 class PhraseCandidateGenerationResult:
     """Summary of candidate phrase extraction for indexed books.