tg-rich-converter 🚀

A lightweight, zero-dependency Python library that converts standard LLM Markdown, LaTeX formulas, thinking processes, and tables into native Telegram Bot API 10.1+ Rich HTML (sendRichMessage).

Why tg-rich-converter?

Starting with Telegram Bot API 10.1, Telegram introduced Rich Messages (sendRichMessage) supporting:

• Messages up to 32,768 characters (no more 4,096-character limit!).
• Native interactive tables with borders and striping.
• Native LaTeX math rendering (both inline and display equations).
• Expandable spoiler/details blocks for reasoning models (DeepSeek-R1, OpenAI o1/o3, Qwen, Gemini).
• Native lists and advanced typography (<ul>, <ol>, <u>, <mark>).

However, LLMs (OpenAI, Anthropic, DeepSeek, Ollama) still output plain Markdown and LaTeX. tg-rich-converter bridges this gap seamlessly in a single function call.

Features

• 📊 Robust Native Tables: Converts standard Markdown pipe tables into <table bordered striped> with column alignment (left, center, right). Safely handles formulas with pipes ($|\psi\rangle$, $|x| \ge 0$) and escaped pipes (\|) inside table cells without breaking columns.
• 🧮 LaTeX Math: Converts $$...$$ into <tg-math-block> and $x$ into <tg-math>.
• 🧠 Customizable AI Thinking Blocks: Converts <think>...</think> tags from reasoning models into expandable <details><summary>Размышления</summary>...</details> blocks with configurable summary titles.
• 🛡️ HTML-Safe: Automatically escapes raw <, >, and & in regular text (e.g. mathematical conditions like x < 5 and y > 10), completely preventing Telegram API 400 Bad Request: can't parse entities errors.
• 📋 Native Lists: Converts unordered (- , * , + ) and ordered (1. ) lists into native <ul> and <ol> tags, avoiding conflicts between asterisk bullet markers and italics.
• 🎨 Rich Typography: Supports bold (**), italic (* / _), strikethrough (~~), underline (++text++), highlight (==text==), and spoilers (||spoiler||) with snake_case protection.
• 💻 Syntax-Highlighted Code: Converts ```python into <pre><code class="language-python"> preserving quotes and copy-paste buttons.
• ⚡ Thread-Safe & Zero Dependencies: Pure standard Python (re, html). Fully reentrant and async-safe for high-concurrency bot environments.

Installation

pip install tg-rich-converter

Quick Start

from tg_rich_converter import to_rich

llm_output = """
# Quantum Computing Report

| Algorithm | State | Complexity | Option |
|:----------|:-----:|:----------:|-------:|
| Linear Search | $N$ items | $O(N)$ | Mode A \\| B |
| State Vector  | $|\\psi\\rangle$ | $O(1)$ | Basic |

### Key Formula
$$|\\psi\\rangle = \\alpha |0\\rangle + \\beta |1\\rangle$$

Stability requires delta < 0.05 and alpha > 0.

<think>
Evaluating time complexity and qubit entanglement...
</think>
"""

# Default thinking summary is "Размышления"
rich_html = to_rich(llm_output)

# Or specify a custom summary:
rich_html_en = to_rich(llm_output, thinking_summary="Reasoning Process")

Framework Integrations

1. aiogram (3.31+)

from aiogram import Bot
from tg_rich_converter import to_rich

bot = Bot(token="YOUR_BOT_TOKEN")

rich_html = to_rich(llm_response)
await bot.send_rich_message(
    chat_id=chat_id,
    rich_message={"html": rich_html}
)

2. pyTelegramBotAPI (telebot 4.36+)

import telebot
from tg_rich_converter import to_rich

bot = telebot.TeleBot("YOUR_BOT_TOKEN")

rich_html = to_rich(llm_response)
bot.send_rich_message(
    chat_id=chat_id,
    rich_message={"html": rich_html}
)

3. Direct HTTP (requests / httpx / urllib)

import requests
from tg_rich_converter import to_rich

rich_html = to_rich(llm_response)

requests.post(
    f"https://api.telegram.org/bot{BOT_TOKEN}/sendRichMessage",
    json={
        "chat_id": chat_id,
        "rich_message": {
            "html": rich_html
        }
    }
)

Testing

Run unit tests locally:

pytest

License

MIT License. Free for commercial and personal use.