fix: render AI replies as Telegram HTML so bold/italic show instead of literal asterisks (v0.14.2)

Author: dervish666

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to UnraidMonitor will be documented in this file.
 
+## [0.14.2] - 2026-06-05
+
+### Fixed
+- **AI replies no longer show literal `*` characters** — the LLM returns standard CommonMark (`**bold**`, `### headings`, `*italic*`), but the natural-language chat handler sent it with no parse mode (so the asterisks rendered literally) and `/diagnose` sent it as Telegram legacy Markdown (which can't parse `**`, silently stripping the formatting). Model output is now converted to Telegram **HTML** before sending, so bold/italic/headings/code render correctly. HTML is the most forgiving parse target — text is escaped and only balanced tags are emitted, so an unmatched delimiter degrades to harmless text instead of breaking the whole message.
+
+### Added
+- `src/utils/telegram_format.py` — `markdown_to_telegram_html()` converter (snake_case- and math-safe emphasis rules, fenced/inline code, links, list markers) plus `strip_html_tags()` for the plain-text fallback. Applied to NL chat, `/diagnose` (+ details), and the Diagnose alert button.
+
 ## [0.14.1] - 2026-06-05
 
 ### Fixed

CLAUDE.md

@@ -92,7 +92,7 @@ src/utils/version_store.py - read/write data/announced_version.json for startup
 
 ## Project Overview
 
-Unraid Server Monitor Bot (v0.14.1) - A Docker-based Telegram bot for monitoring Unraid servers. Monitors Docker containers (events, logs, resources) and Unraid server health (CPU, memory, disks, array, UPS). Uses multi-provider LLM support (Anthropic, OpenAI, Ollama) for AI-powered diagnostics and natural language interaction. Sends alerts via Telegram with quick-action buttons.
+Unraid Server Monitor Bot (v0.14.2) - A Docker-based Telegram bot for monitoring Unraid servers. Monitors Docker containers (events, logs, resources) and Unraid server health (CPU, memory, disks, array, UPS). Uses multi-provider LLM support (Anthropic, OpenAI, Ollama) for AI-powered diagnostics and natural language interaction. Sends alerts via Telegram with quick-action buttons.
 
 **Version string lives in TWO places** — `pyproject.toml` (`version`) and `src/__init__.py` (`__version__`). Both must be bumped together on release; `tests/test_version.py` guards against drift. `BOT_VERSION` (in `src/bot/health_command.py`) resolves from installed package metadata when available, else falls back to `src.__version__` — the package is not installed in the Docker image, so the `__version__` fallback is what runs in production.
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unraid-monitor-bot"
-version = "0.14.1"
+version = "0.14.2"
 requires-python = ">=3.11"
 dependencies = [
     "docker>=7.0.0,<8.0.0",

src/__init__.py

@@ -1 +1 @@
-__version__ = "0.14.1"
+__version__ = "0.14.2"

src/bot/alert_callbacks.py

@@ -1,6 +1,7 @@
 """Callback handlers for alert action buttons."""
 
 import asyncio
+import html
 import logging
 import re
 from datetime import timedelta
@@ -27,6 +28,7 @@
 from src.services.diagnostic import DiagnosticService
 from src.utils.formatting import validate_container_name, escape_markdown, truncate_callback_data, format_duration_minutes
 from src.utils.sanitize import sanitize_logs_for_display
+from src.utils.telegram_format import markdown_to_telegram_html
 
 if TYPE_CHECKING:
     from src.alerts.array_mute_manager import ArrayMuteManager
@@ -265,15 +267,16 @@ async def handler(callback: CallbackQuery) -> None:
         context.brief_summary = analysis
         diagnostic_service.store_context(user_id, context)
 
-        response = f"""*Diagnosis: {escape_markdown(actual_name)}*
-
-{analysis}
-
-_Want more details?_"""
+        # analysis is LLM Markdown; render the whole reply as Telegram HTML.
+        response = (
+            f"<b>Diagnosis: {html.escape(actual_name)}</b>\n\n"
+            f"{markdown_to_telegram_html(analysis)}\n\n"
+            f"<i>Want more details?</i>"
+        )
 
         if callback.message:
             try:
-                await callback.message.answer(response, parse_mode="Markdown")
+                await callback.message.answer(response, parse_mode="HTML")
             except TelegramBadRequest:
                 plain_response = f"Diagnosis: {actual_name}\n\n{analysis}\n\nWant more details?"
                 await callback.message.answer(plain_response)

src/bot/diagnose_command.py

@@ -1,5 +1,6 @@
 """Diagnose command handler for AI-powered container analysis."""
 
+import html
 import logging
 import re
 from typing import Callable, Awaitable
@@ -10,6 +11,7 @@
 from src.state import ContainerStateManager
 from src.services.diagnostic import DiagnosticService
 from src.utils.formatting import safe_reply
+from src.utils.telegram_format import markdown_to_telegram_html
 
 logger = logging.getLogger(__name__)
 
@@ -120,11 +122,13 @@ async def handler(message: Message) -> None:
             ],
         ])
 
-        response = f"""*Diagnosis: {actual_name}*
-
-{analysis}"""
+        # analysis is LLM Markdown; render the whole reply as Telegram HTML.
+        response = (
+            f"<b>Diagnosis: {html.escape(actual_name)}</b>\n\n"
+            f"{markdown_to_telegram_html(analysis)}"
+        )
 
-        await safe_reply(message, response, reply_markup=keyboard)
+        await safe_reply(message, response, parse_mode="HTML", reply_markup=keyboard)
 
     return handler
 
@@ -153,9 +157,9 @@ async def handler(callback: CallbackQuery) -> None:
 
         details = await diagnostic_service.get_details(user_id)
         if details:
-            response = f"*Detailed Analysis*\n\n{details}"
+            response = f"<b>Detailed Analysis</b>\n\n{markdown_to_telegram_html(details)}"
             if isinstance(callback.message, Message):
-                await safe_reply(callback.message, response)
+                await safe_reply(callback.message, response, parse_mode="HTML")
         else:
             if callback.message:
                 await callback.message.answer("Could not generate detailed analysis.")

src/bot/nl_handler.py

@@ -6,7 +6,8 @@
 from aiogram.filters import BaseFilter
 from aiogram.types import Message, InlineKeyboardMarkup, InlineKeyboardButton
 
-from src.utils.formatting import truncate_message
+from src.utils.formatting import safe_reply, truncate_message
+from src.utils.telegram_format import markdown_to_telegram_html
 
 logger = logging.getLogger(__name__)
 
@@ -65,7 +66,17 @@ async def handler(message: Message) -> None:
                 ]
             ])
 
-        await message.answer(truncate_message(result.response), reply_markup=reply_markup)
+        # The LLM returns CommonMark Markdown; render it as Telegram HTML so
+        # bold/italic/headings display instead of leaking literal '*' characters.
+        # Truncate after conversion so the final HTML stays within Telegram's
+        # length limit (a cut tag degrades to plain text via safe_reply).
+        html_response = truncate_message(
+            markdown_to_telegram_html(result.response),
+            suffix="\n\n<i>(truncated)</i>",
+        )
+        await safe_reply(
+            message, html_response, parse_mode="HTML", reply_markup=reply_markup
+        )
 
     return handler
 

src/constants.py

@@ -97,6 +97,9 @@
 # Shown once when BOT_VERSION first differs from data/announced_version.json.
 ANNOUNCED_VERSION_PATH = "data/announced_version.json"
 WHATS_NEW: dict[str, list[str]] = {
+    "0.14.2": [
+        "Cleaner AI replies - chat and /diagnose answers now render bold, italics and code properly instead of showing raw ** asterisks",
+    ],
     "0.14.0": [
         "Turn features on from Telegram - /manage → ⚙️ Features explains and enables image-update alerts and lets you pick auto-heal containers, no config file editing",
     ],

src/utils/formatting.py

@@ -8,6 +8,7 @@
 from aiogram.exceptions import TelegramBadRequest
 
 from src.constants import MAX_CONTAINER_NAME_LENGTH
+from src.utils.telegram_format import strip_html_tags
 
 # Valid Docker container name pattern (alphanumeric, dash, underscore, dot, colon)
 # Docker allows: [a-zA-Z0-9][a-zA-Z0-9_.-]* but we also allow colons for compose names
@@ -26,18 +27,25 @@ def _strip_markdown(text: str) -> str:
     return text.replace("*", "").replace("`", "").replace("_", "").replace("[", "").replace("]", "")
 
 
+def _plain_fallback(text: str, parse_mode: str | None) -> str:
+    """Reduce formatted text to plain text for the parse-failure fallback."""
+    if parse_mode == "HTML":
+        return strip_html_tags(text)
+    return _strip_markdown(text)
+
+
 async def safe_reply(
     message: Message,
     text: str,
     parse_mode: str = "Markdown",
     **kwargs: Any,
 ) -> Message:
-    """Send a message with Markdown, falling back to plain text on parse failure."""
+    """Send a formatted message, falling back to plain text on parse failure."""
     try:
         return await message.answer(text, parse_mode=parse_mode, **kwargs)
     except TelegramBadRequest as e:
         if "can't parse entities" in str(e):
-            return await message.answer(_strip_markdown(text), **kwargs)
+            return await message.answer(_plain_fallback(text, parse_mode), **kwargs)
         raise
 
 
@@ -47,12 +55,12 @@ async def safe_edit(
     parse_mode: str = "Markdown",
     **kwargs: Any,
 ) -> Message | bool:
-    """Edit a message with Markdown, falling back to plain text on parse failure."""
+    """Edit a message with formatting, falling back to plain text on parse failure."""
     try:
         return await message.edit_text(text, parse_mode=parse_mode, **kwargs)  # type: ignore[union-attr]
     except TelegramBadRequest as e:
         if "can't parse entities" in str(e):
-            return await message.edit_text(_strip_markdown(text), **kwargs)  # type: ignore[union-attr]
+            return await message.edit_text(_plain_fallback(text, parse_mode), **kwargs)  # type: ignore[union-attr]
         raise
 
 

src/utils/telegram_format.py

@@ -0,0 +1,113 @@
+"""Convert LLM-generated Markdown into Telegram-safe HTML.
+
+The LLM providers (Anthropic, OpenAI, Ollama) return standard CommonMark:
+``**bold**``, ``# headings``, ``*italic*``, ``` ``` ``` fenced code blocks. Telegram's
+legacy Markdown parse mode does not understand double-asterisk bold or
+headings, so that output renders with literal ``*`` characters all over it
+(or fails to parse and gets stripped to plain text entirely).
+
+Telegram's HTML parse mode is the most forgiving target for arbitrary model
+output: the text is HTML-escaped first and we only ever emit a small set of
+*balanced* tags (``<b>``, ``<i>``, ``<code>``, ``<pre>``, ``<a>``, ``<s>``), so an
+unmatched Markdown delimiter degrades to a harmless literal character instead
+of breaking the whole message. See the Telegram Bot API "HTML style" docs for
+the supported tag set.
+"""
+
+import html
+import re
+
+__all__ = ["markdown_to_telegram_html", "strip_html_tags"]
+
+# Fenced code blocks: ```lang\n ... ``` (contents preserved verbatim).
+_FENCE_RE = re.compile(r"```[^\n]*\n?(.*?)```", re.DOTALL)
+# Inline code: `code`.
+_INLINE_CODE_RE = re.compile(r"`([^`\n]+)`")
+# Markdown links: [text](url).
+_LINK_RE = re.compile(r"\[([^\]\n]+)\]\((https?://[^)\s]+)\)")
+# Headings: up to three leading spaces, 1-6 '#', text, optional trailing '#'.
+_HEADING_RE = re.compile(r"^[ \t]{0,3}#{1,6}[ \t]+(.+?)[ \t]*#*[ \t]*$", re.MULTILINE)
+# Bold: **text** / __text__ (no surrounding word char for underscores).
+_BOLD_STAR_RE = re.compile(r"\*\*(?=\S)(.+?)(?<=\S)\*\*")
+_BOLD_UNDER_RE = re.compile(r"(?<!\w)__(?=\S)(.+?)(?<=\S)__(?!\w)")
+# Italic: *text* / _text_ (single delimiter, no adjacent space, snake_case-safe).
+_ITALIC_STAR_RE = re.compile(r"(?<!\*)\*(?!\s)([^*\n]+?)(?<!\s)\*(?!\*)")
+_ITALIC_UNDER_RE = re.compile(r"(?<!\w)_(?=\S)([^_\n]+?)(?<=\S)_(?!\w)")
+# Strikethrough: ~~text~~.
+_STRIKE_RE = re.compile(r"~~(?=\S)(.+?)(?<=\S)~~")
+# List markers using '*' or '+' (a literal '*' bullet would otherwise show raw).
+_BULLET_RE = re.compile(r"^([ \t]*)[*+][ \t]+(?=\S)", re.MULTILINE)
+# Placeholder token used to protect code spans from further processing.
+_PLACEHOLDER_RE = re.compile(r"\x00(\d+)\x00")
+_TAG_RE = re.compile(r"<[^>]+>")
+
+
+def markdown_to_telegram_html(text: str) -> str:
+    """Convert Markdown produced by an LLM into Telegram-safe HTML.
+
+    Args:
+        text: Raw model output in CommonMark-ish Markdown.
+
+    Returns:
+        HTML suitable for ``parse_mode="HTML"``. Returns an empty string for
+        empty input.
+    """
+    if not text:
+        return ""
+
+    protected: list[str] = []
+
+    def _stash(fragment: str) -> str:
+        protected.append(fragment)
+        return f"\x00{len(protected) - 1}\x00"
+
+    # 1. Pull out code (fenced first, then inline) and escape its contents now,
+    #    so later Markdown/HTML passes never touch it.
+    def _repl_fence(m: re.Match[str]) -> str:
+        return _stash(f"<pre>{html.escape(m.group(1).rstrip(chr(10)), quote=False)}</pre>")
+
+    def _repl_inline_code(m: re.Match[str]) -> str:
+        return _stash(f"<code>{html.escape(m.group(1), quote=False)}</code>")
+
+    text = _FENCE_RE.sub(_repl_fence, text)
+    text = _INLINE_CODE_RE.sub(_repl_inline_code, text)
+
+    # 2. Escape everything else. Telegram HTML only requires &, < and > to be
+    #    escaped in text; quotes are left intact so they read naturally. Markdown
+    #    delimiters (*, _, #, [, ]) survive escaping, so the regex passes below
+    #    still work; '\x00' placeholders are untouched.
+    text = html.escape(text, quote=False)
+
+    # 3. Links -> <a>. The captured url already had '&' escaped to '&amp;'; also
+    #    make any quote attribute-safe inside the href.
+    def _repl_link(m: re.Match[str]) -> str:
+        label, url = m.group(1), m.group(2).replace('"', "&quot;")
+        return _stash(f'<a href="{url}">{label}</a>')
+
+    text = _LINK_RE.sub(_repl_link, text)
+
+    # 4. Headings -> bold line.
+    text = _HEADING_RE.sub(r"<b>\1</b>", text)
+
+    # 5. Bold, then italic, then strikethrough.
+    text = _BOLD_STAR_RE.sub(r"<b>\1</b>", text)
+    text = _BOLD_UNDER_RE.sub(r"<b>\1</b>", text)
+    text = _ITALIC_STAR_RE.sub(r"<i>\1</i>", text)
+    text = _ITALIC_UNDER_RE.sub(r"<i>\1</i>", text)
+    text = _STRIKE_RE.sub(r"<s>\1</s>", text)
+
+    # 6. Normalise '*'/'+' bullets to a clean glyph ('-' bullets already read
+    #    fine and are left as-is).
+    text = _BULLET_RE.sub(r"\1• ", text)
+
+    # 7. Collapse the doubled tags a heading-with-bold produces (e.g. '## **x**').
+    text = text.replace("<b><b>", "<b>").replace("</b></b>", "</b>")
+
+    # 8. Restore protected code/link fragments.
+    text = _PLACEHOLDER_RE.sub(lambda m: protected[int(m.group(1))], text)
+    return text
+
+
+def strip_html_tags(text: str) -> str:
+    """Strip HTML tags and unescape entities for a plain-text fallback."""
+    return html.unescape(_TAG_RE.sub("", text))