From a81ed70b14a75cacd6779436e08ef4077c54c121 Mon Sep 17 00:00:00 2001
From: JB <jb-apps@outlook.com>
Date: Sun, 26 Oct 2025 10:04:36 -0700
Subject: [PATCH] feat: Update LLM context handling and prompt template for
 improved clarity and legacy support

---
 abogen/kokoro_text_normalization.py |  3 ++-
 abogen/normalization_settings.py    | 24 +++++++++++++++++++++++-
 abogen/web/routes.py                |  2 +-
 abogen/web/templates/settings.html  |  2 +-
 4 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/abogen/kokoro_text_normalization.py b/abogen/kokoro_text_normalization.py
index f99dc18..151a36d 100644
--- a/abogen/kokoro_text_normalization.py
+++ b/abogen/kokoro_text_normalization.py
@@ -727,12 +727,13 @@ def _normalize_with_llm(
             normalized_lines.append(line_body + newline)
             continue
 
+        paragraph_context = core
         rewritten_sentences: List[str] = []
         for sentence in sentences:
             prompt_context = {
                 "text": sentence,
                 "sentence": sentence,
-                "paragraph": sentence,
+                "paragraph": paragraph_context,
             }
             prompt = _render_mustache(prompt_template, prompt_context)
             completion = generate_completion(
diff --git a/abogen/normalization_settings.py b/abogen/normalization_settings.py
index 5fd8323..2f300fa 100644
--- a/abogen/normalization_settings.py
+++ b/abogen/normalization_settings.py
@@ -16,6 +16,13 @@ DEFAULT_LLM_PROMPT = (
     "Sentence: {{ sentence }}"
 )
 
+_LEGACY_REWRITE_ONLY_PROMPT = (
+    "You are assisting with audiobook preparation. Rewrite the provided sentence so apostrophes and "
+    "contractions are unambiguous for text-to-speech. Respond with only the rewritten sentence.\n"
+    "Sentence: {{ sentence }}\n"
+    "Context: {{ paragraph }}"
+)
+
 _SETTINGS_DEFAULTS: Dict[str, Any] = {
     "llm_base_url": "",
     "llm_api_key": "",
@@ -67,7 +74,10 @@ def _environment_defaults() -> Dict[str, Any]:
 
 
 def environment_llm_defaults() -> Dict[str, Any]:
-    return dict(_environment_defaults())
+    defaults = dict(_environment_defaults())
+    if defaults:
+        _apply_llm_migrations(defaults)
+    return defaults
 
 
 def _coerce_bool(value: Any, default: bool) -> bool:
@@ -89,6 +99,16 @@ def _coerce_float(value: Any, default: float) -> float:
         return default
 
 
+def _apply_llm_migrations(settings: Dict[str, Any]) -> None:
+    prompt_value = str(settings.get("llm_prompt") or "")
+    if prompt_value.strip() == _LEGACY_REWRITE_ONLY_PROMPT.strip():
+        settings["llm_prompt"] = DEFAULT_LLM_PROMPT
+
+    context_mode = str(settings.get("llm_context_mode") or "").strip().lower()
+    if context_mode != "sentence":
+        settings["llm_context_mode"] = "sentence"
+
+
 def _extract_settings(source: Mapping[str, Any]) -> Dict[str, Any]:
     env_defaults = _environment_defaults()
     extracted: Dict[str, Any] = {}
@@ -105,6 +125,7 @@ def _extract_settings(source: Mapping[str, Any]) -> Dict[str, Any]:
             extracted[key] = _coerce_float(raw_value, default)
         else:
             extracted[key] = str(raw_value or "") if isinstance(default, str) else raw_value
+    _apply_llm_migrations(extracted)
     return extracted
 
 
@@ -148,4 +169,5 @@ def apply_overrides(base: Mapping[str, Any], overrides: Mapping[str, Any]) -> Di
         if key not in _SETTINGS_DEFAULTS:
             continue
         merged[key] = value
+    _apply_llm_migrations(merged)
     return merged
diff --git a/abogen/web/routes.py b/abogen/web/routes.py
index 195e32e..8dcfedf 100644
--- a/abogen/web/routes.py
+++ b/abogen/web/routes.py
@@ -2025,7 +2025,7 @@ def _normalize_setting_value(key: str, value: Any, defaults: Dict[str, Any]) ->
     if key == "llm_context_mode":
         if isinstance(value, str):
             normalized_scope = value.strip().lower()
-            if normalized_scope in {"sentence", "paragraph"}:
+            if normalized_scope == "sentence":
                 return normalized_scope
         return defaults[key]
     if key == "llm_prompt":
diff --git a/abogen/web/templates/settings.html b/abogen/web/templates/settings.html
index 431cfeb..3f781ed 100644
--- a/abogen/web/templates/settings.html
+++ b/abogen/web/templates/settings.html
@@ -209,7 +209,7 @@
             <div class="field">
               <label for="llm_prompt">Prompt Template</label>
               <textarea id="llm_prompt" name="llm_prompt" rows="6">{{ settings.llm_prompt }}</textarea>
-              <p class="hint">Use placeholders like <code>{{ '{{sentence}}' }}</code> and <code>{{ '{{paragraph}}' }}</code> to inject content.</p>
+              <p class="hint">Use <code>{{ '{{sentence}}' }}</code> for the active sentence. <code>{{ '{{paragraph}}' }}</code> remains available for legacy prompts.</p>
             </div>
             <div class="field field--choices">
               <span class="field__label">Context Mode</span>