Tg-Rich-Converter: Streaming LLM Markdown and LaTeX to Telegram Bot API 10.1

A new zero-dependency Python library, tg-rich-converter, converts LLM Markdown, LaTeX formulas, reasoning tags, and tables into native Telegram Bot API 10.1 Rich HTML for the sendRichMessage endpoint. The library supports Telegram's 32,768-character Rich Message limit, native tables, inline and display LaTeX via tg-math and tg-math-block tags, and expandable details blocks for reasoning models including DeepSeek-R1, OpenAI o1/o3, Qwen, and Gemini. It is installable via pip install tg-rich-converter and ships with a tg-rich CLI, a streaming mode that auto-balances unclosed code blocks, think tags, and LaTeX delimiters to prevent Telegram 400 Bad Request parse errors, and a local preview.html generator.

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 . 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 or via the CLI command line tool . - 🌊 LLM Streaming Mode streaming=True : Auto-balances unclosed code blocks , reasoning tags <think , unclosed LaTeX formulas $$ / $ , and unclosed inline styles , || , ++ , == , ~~ during token-by-token streaming, completely preventing Telegram 400 Bad Request: can't parse entities errors on live message edits. - 📊 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 markdown code fences into <pre <code class="language-..." preserving language classes, indentation, and copy buttons. - ✂️ Smart Message Splitter: Safely splits long texts up to 32,768 Telegram Rich limit or 4,096 Classic limit characters. Automatically closes and re-opens nested tags with attributes <pre <code class="..." , <blockquote , and protects LaTeX formulas from fragmentation. - 👁️ Local HTML Preview: Instantly generates a standalone preview.html styled with authentic Telegram Web dark theme and KaTeX client-side math rendering to visually inspect output without launching a bot. - 🚀 Built-in CLI tg-rich : Fast command-line utility with TrueColor ANSI logo, preview generator, auto-opening in browser, pipeline support stdin / stdout , and batch message splitter. - ⚡ Thread-Safe & Zero Dependencies: Pure standard Python re , html , argparse . Fully reentrant and async-safe for high-concurrency bot environments. pip install tg-rich-converter python 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" When streaming LLM responses token-by-token OpenAI , DeepSeek-R1 , Anthropic Claude , Ollama , intermediate tokens frequently contain unfinished Markdown/LaTeX structures: - Unclosed code fences: python\ndef run : missing closing - Open reasoning blocks: <think Analyzing steps... missing </think - Half-written formulas: $E = mc^2 or $$\int 0^\infty - Incomplete typography: bold text , ||secret key , ++underlined Passing streaming=True automatically balances and virtually closes all open structures in LIFO order for every frame: python import time from tg rich converter import to rich 1. Send initial placeholder message via sendRichMessage sent msg = await bot.send rich message chat id=chat id, rich message={"html": "<i ⏳ Thinking...</i "} buffer = "" last edit time = time.time THROTTLE SECONDS = 0.7 Recommended: 0.6 - 0.8s to avoid Telegram 429 Flood Limits 2. Stream tokens from LLM async for chunk in openai client.chat.completions.create ..., stream=True : buffer += chunk.choices 0 .delta.content or "" now = time.time Edit message with rate-limiting throttle if now - last edit time = THROTTLE SECONDS: safe frame html = to rich buffer, streaming=True await bot.edit message text chat id=chat id, message id=sent msg.message id, rich message={"html": safe frame html} Must pass rich message, NOT text/parse mode last edit time = now 3. Final complete render streaming=False final html = to rich buffer, streaming=False await bot.edit message text chat id=chat id, message id=sent msg.message id, rich message={"html": final html} - Cause: Calling sendMessage or editMessageText with legacy text="<details ..." and parse mode="HTML" . The legacy Telegram parser does not support <details , <tg-math , or <table . - Fix: Use the Telegram Bot API 10.1+ Rich Message format with rich message={"html": ...} : ❌ WRONG Triggers 400 Bad Request : await bot.edit message text chat id=chat id, message id=msg id, text=rich html, parse mode="HTML" ✔ CORRECT Native Rich Messages : await bot.edit message text chat id=chat id, message id=msg id, rich message={"html": rich html} - Cause: Sending editMessageText on every single incoming LLM token. - Fix: Throttle live edits to once every 0.6 – 0.8 seconds or every 40–60 characters . - Fix: Customize the default title via thinking summary : html output = to rich markdown text, thinking summary="Chain of Thought" After installation, the tg-rich command is available in your terminal: Convert a markdown file and open the interactive Telegram preview directly in your default browser: tg-rich prompt response.md --preview --open tg-rich document.md -o output.html cat llm output.md | tg-rich telegram message.html Split a large document into chunks respecting Telegram character limits: Split for Rich Messages 32k limit tg-rich big report.md --split Split for Classic Messages 4k limit into separate files tg-rich big report.md --split --limit 4096 -o chunk.html | Flag | Description | Default | |---|---|---| | input file | Path to markdown file or - / pipe for stdin | - | | -o, --output FILE | Write converted HTML to file instead of stdout | stdout | | -p, --preview FILE | Generate standalone preview.html with KaTeX & Telegram Dark theme | preview.html | | --open | Automatically open the preview in default web browser | False | | -s, --split | Split long message into safe Telegram chunks | False | | -l, --limit INT | Maximum character length for splitting | 32768 | | -t, --thinking-summary TEXT | Custom header for <think reasoning blocks | Размышления | | --lang {ru,en} | Interface and error message language | auto | | -q, --quiet | Suppress banner and progress messages in stderr | False | | -v, --version | Display current library version | | When LLM output exceeds Telegram limits 32,768 chars for Rich Messages or 4,096 chars for standard messages , naive slicing breaks open HTML tags and crashes the bot. Use split rich message : python from tg rich converter import split rich message Automatically converts Markdown to Rich HTML and splits into safe chunks chunks = split rich message long llm response, max length=32768, 32,768 for Rich Messages default or 4,096 for Classic is markdown=True, Automatically runs to rich thinking summary="Reasoning" Each chunk is guaranteed to be valid HTML with all open tags closed and reopened for chunk in chunks: await bot.send rich message chat id=chat id, rich message={"html": chunk} Visualize how your message will look in Telegram Desktop/Mobile without running a bot or sending messages: python from tg rich converter import save preview Generates preview.html with Telegram dark theme, KaTeX formulas, and interactive spoilers save preview llm output, file path="preview.html", title="LLM Telegram Preview" Double click preview.html to open it in your browser python 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} python 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} python 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 } } Run the comprehensive test suite locally 44 tests, 100% pass : pytest Test real-time LLM token-by-token streaming with rate-limiting throttle 0.7s directly in your Telegram chat: Direct CLI arguments python demo streaming.py --token "YOUR BOT TOKEN" --chat-id "YOUR CHAT ID" Or via environment variables export BOT TOKEN="YOUR BOT TOKEN" export CHAT ID="YOUR CHAT ID" python demo streaming.py Windows PowerShell $env:BOT TOKEN="YOUR BOT TOKEN"; $env:CHAT ID="YOUR CHAT ID"; python demo streaming.py Validate intermediate streaming frames in terminal without sending requests to Telegram: python demo streaming.py MIT License. Free for commercial and personal use.