DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""LaTeX/math verbalizer for the TTS pre-layer.
``strip_markdown_for_speech`` already drops Markdown structure. This module
turns the remaining math into words a voice model can read without saying
"dollar", "backslash", "caret", or "underscore".
Scope is deliberately Pareto, not a full MathSpeak engine:
* Only math islands (``$…$``, ``$$…$$``, ``\\(…\\)``, ``\\[…\\]``,
``\\begin{equation|align|…}``) get script handling (``^`` / ``_``), so
snake_case prose is left alone.
* High-frequency algebra is verbalized: fractions, roots, limits, Greek,
relations, trig/log, blackboard number sets.
* Structural TeX (``\\left``, braces, environments) is stripped.
* Function words are English; they are portable across OpenAI-compatible TTS
engines, including Chinese voices that already mix English math terms.
"""
from __future__ import annotations
from collections.abc import Callable
import re
# ── lexicons ──────────────────────────────────────────────────────────────
_GREEK = {
"alpha": "alpha",
"beta": "beta",
"gamma": "gamma",
"delta": "delta",
"epsilon": "epsilon",
"varepsilon": "epsilon",
"zeta": "zeta",
"eta": "eta",
"theta": "theta",
"vartheta": "theta",
"iota": "iota",
"kappa": "kappa",
"lambda": "lambda",
"mu": "mu",
"nu": "nu",
"xi": "xi",
"pi": "pi",
"varpi": "pi",
"rho": "rho",
"sigma": "sigma",
"varsigma": "sigma",
"tau": "tau",
"upsilon": "upsilon",
"phi": "phi",
"varphi": "phi",
"chi": "chi",
"psi": "psi",
"omega": "omega",
"Alpha": "capital alpha",
"Beta": "capital beta",
"Gamma": "capital gamma",
"Delta": "capital delta",
"Theta": "capital theta",
"Lambda": "capital lambda",
"Xi": "capital xi",
"Pi": "capital pi",
"Sigma": "capital sigma",
"Phi": "capital phi",
"Psi": "capital psi",
"Omega": "capital omega",
}
_FUNCTIONS = {
"arcsin": "arcsine",
"arccos": "arccosine",
"arctan": "arctangent",
"sinh": "hyperbolic sine",
"cosh": "hyperbolic cosine",
"tanh": "hyperbolic tangent",
"sin": "sine",
"cos": "cosine",
"tan": "tangent",
"cot": "cotangent",
"sec": "secant",
"csc": "cosecant",
"log": "log",
"ln": "natural log",
"lg": "log",
"exp": "exponential",
"min": "min",
"max": "max",
"inf": "infimum",
"sup": "supremum",
"det": "determinant",
"dim": "dimension",
"ker": "kernel",
"deg": "degree",
"gcd": "GCD",
"lcm": "LCM",
"arg": "arg",
"Pr": "probability",
}
_OPERATORS = {
"leqslant": "less than or equal to",
"geqslant": "greater than or equal to",
"subseteq": "subset of or equal to",
"supseteq": "superset of or equal to",
"leftrightarrow": "if and only if",
"Leftrightarrow": "if and only if",
"rightarrow": "to",
"Rightarrow": "implies",
"leftarrow": "from",
"Leftarrow": "implied by",
"longrightarrow": "to",
"infty": "infinity",
"emptyset": "empty set",
"varnothing": "empty set",
"partial": "partial",
"nabla": "del",
"cdots": "dot dot dot",
"ldots": "dot dot dot",
"dots": "dot dot dot",
"cdot": "times",
"times": "times",
"star": "star",
"ast": "times",
"div": "divided by",
"pm": "plus or minus",
"mp": "minus or plus",
"leq": "less than or equal to",
"geq": "greater than or equal to",
"neq": "not equal to",
"ne": "not equal to",
"approx": "approximately",
"equiv": "equivalent to",
"sim": "similar to",
"propto": "proportional to",
"cong": "congruent to",
"forall": "for all",
"exists": "there exists",
"notin": "not in",
"subset": "subset of",
"supset": "superset of",
"cup": "union",
"cap": "intersection",
"vee": "or",
"wedge": "and",
"oplus": "plus",
"otimes": "tensor",
"land": "and",
"lor": "or",
"lnot": "not",
"neg": "not",
"to": "to",
"gets": "from",
"implies": "implies",
"iff": "if and only if",
"in": "in",
"ni": "contains",
"le": "less than or equal to",
"ge": "greater than or equal to",
"ll": "much less than",
"gg": "much greater than",
"mid": "given",
"parallel": "parallel to",
"perp": "perpendicular to",
"degree": "degrees",
"circ": "compose",
"bullet": "times",
"prime": "prime",
"ell": "l",
"hbar": "h bar",
"Re": "real part",
"Im": "imaginary part",
}
_SPACING_DROP = {
"qquad": " ",
"quad": " ",
"hspace": "",
"vspace": "",
"phantom": "",
"mathstrut": "",
"displaystyle": "",
"textstyle": "",
"scriptstyle": "",
"left": "",
"right": "",
"bigl": "",
"bigr": "",
"Bigl": "",
"Bigr": "",
"biggl": "",
"biggr": "",
"Biggl": "",
"Biggr": "",
"big": "",
"Big": "",
"bigg": "",
"Bigg": "",
"nolimits": "",
"limits": "",
"notag": "",
"tag": "",
"label": "",
}
_BLACKBOARD = {
"R": "the reals",
"N": "the naturals",
"Z": "the integers",
"Q": "the rationals",
"C": "the complexes",
}
_MATH_ENVS = frozenset(
{
"equation",
"equation*",
"align",
"align*",
"aligned",
"gather",
"gather*",
"displaymath",
"math",
"cases",
"array",
"matrix",
"pmatrix",
"bmatrix",
"vmatrix",
"Vmatrix",
"multline",
"split",
}
)
_UNICODE_MATH = {
"≤": " less than or equal to ",
"≥": " greater than or equal to ",
"≠": " not equal to ",
"≈": " approximately ",
"≡": " equivalent to ",
"∞": " infinity ",
"×": " times ",
"÷": " divided by ",
"±": " plus or minus ",
"→": " to ",
"←": " from ",
"⇒": " implies ",
"⇔": " if and only if ",
"∈": " in ",
"∉": " not in ",
"⊂": " subset of ",
"⊆": " subset of or equal to ",
"∪": " union ",
"∩": " intersection ",
"∀": " for all ",
"∃": " there exists ",
"∂": " partial ",
"∇": " del ",
"√": " square root of ",
"∑": " sum ",
"∏": " product ",
"∫": " integral ",
"°": " degrees ",
"·": " times ",
"⋅": " times ",
}
_STYLE_NAMES = (
"operatorname",
"boldsymbol",
"mathbf",
"mathbb",
"mathcal",
"mathit",
"mathsf",
"mathtt",
"textrm",
"textbf",
"textit",
"mathrm",
"text",
"mbox",
"overline",
"underline",
"widehat",
"widetilde",
"hat",
"bar",
"vec",
"dot",
"tilde",
"check",
"acute",
"grave",
"breve",
)
_ACCENT_SPEAK = {
"overline": "{inner} bar",
"underline": "{inner} underline",
"widehat": "{inner} hat",
"widetilde": "{inner} tilde",
"hat": "{inner} hat",
"bar": "{inner} bar",
"vec": "{inner} vector",
"dot": "{inner} dot",
"tilde": "{inner} tilde",
"check": "{inner} check",
}
_LIMIT_HEAD = {
"oint": "contour integral",
"int": "integral",
"sum": "sum",
"prod": "product",
"lim": "limit",
}
_FRAC_NAMES = ("dfrac", "tfrac", "cfrac", "frac")
_SIMPLE_OPERAND = re.compile(r"^[\w.]+$", re.UNICODE)
_COMMAND = re.compile(r"\\(?:[a-zA-Z]+|.)")
_BEGIN_ENV = re.compile(r"\\begin\{([^}]+)\}")
_LEFTOVER_DOLLAR = re.compile(r"\$+")
_PAD_PLUS_EQ = re.compile(r"\s*([+=])\s*")
_MULTI_SPACE = re.compile(r"[ \t]{2,}")
_LOOSE_TEX = re.compile(
r"\\(?:"
+ "|".join(
re.escape(name)
for name in sorted(
{
*_GREEK,
*_OPERATORS,
*_FUNCTIONS,
*_SPACING_DROP,
*_FRAC_NAMES,
*_STYLE_NAMES,
*_LIMIT_HEAD,
"sqrt",
"binom",
"mathbb",
},
key=len,
reverse=True,
)
)
+ r")(?![a-zA-Z])"
)
_WINDOWS_PATH = re.compile(r"(?<![A-Za-z0-9])(?:[A-Za-z]:\\|\\\\)[^\s]*")
def _skip_ws(s: str, i: int) -> int:
n = len(s)
while i < n and s[i].isspace():
i += 1
return i
def _is_escaped(s: str, i: int) -> bool:
bs = 0
j = i - 1
while j >= 0 and s[j] == "\\":
bs += 1
j -= 1
return bs % 2 == 1
def _read_group(s: str, i: int) -> tuple[str, int] | None:
"""Read a ``{…}`` group starting at ``i``. Returns ``(inner, after)``."""
if i >= len(s) or s[i] != "{":
return None
depth = 0
j = i
n = len(s)
while j < n:
ch = s[j]
if ch == "\\" and j + 1 < n:
j += 2
continue
if ch == "{":
depth += 1
elif ch == "}":
depth -= 1
if depth == 0:
return s[i + 1 : j], j + 1
j += 1
return None
def _read_tex_token(s: str, i: int) -> tuple[str | None, int]:
"""Read one TeX token: a ``{group}``, a ``\\command``, or one character."""
i = _skip_ws(s, i)
if i >= len(s):
return None, i
if s[i] == "{":
grp = _read_group(s, i)
if grp is None:
return s[i], i + 1
inner, end = grp
return inner, end
match = _COMMAND.match(s, i)
if match:
return match.group(0), match.end()
return s[i], i + 1
def _until_stable(fn, text: str, *, limit: int = 8) -> str:
for _ in range(limit):
nxt = fn(text)
if nxt == text:
return nxt
text = nxt
return text
def _speak_operand(piece: str) -> str:
piece = piece.strip()
if not piece:
return ""
if _SIMPLE_OPERAND.fullmatch(piece):
return piece
return f"({piece})"
def _replace_named_commands(text: str, mapping: dict[str, str]) -> str:
if not mapping:
return text
keys = sorted(mapping, key=len, reverse=True)
pattern = re.compile(r"\\(" + "|".join(re.escape(k) for k in keys) + r")(?![a-zA-Z])")
return pattern.sub(lambda m: f" {mapping[m.group(1)]} ", text)
def _unwrap_style_once(text: str) -> str:
out: list[str] = []
i = 0
n = len(text)
names = "|".join(re.escape(name) for name in _STYLE_NAMES)
opener = re.compile(r"\\(" + names + r")(?![a-zA-Z])")
while i < n:
match = opener.search(text, i)
if not match:
out.append(text[i:])
break
out.append(text[i : match.start()])
i = _skip_ws(text, match.end())
inner, end = _read_tex_token(text, i)
name = match.group(1)
if inner is None:
i = match.end()
continue
spoken = _ACCENT_SPEAK.get(name)
if spoken:
out.append(" " + spoken.format(inner=inner.strip()) + " ")
else:
out.append(inner)
i = end
return "".join(out)
def _replace_blackboard_sets(text: str) -> str:
def repl(match: re.Match[str]) -> str:
letter = match.group(1)
return f" {_BLACKBOARD.get(letter, letter)} "
return re.sub(r"\\mathbb\s*\{([RNZQC])\}", repl, text)
def _replace_frac_once(text: str) -> str:
out: list[str] = []
i = 0
n = len(text)
opener = re.compile(r"\\(?:" + "|".join(_FRAC_NAMES) + r")(?![a-zA-Z])")
while i < n:
match = opener.search(text, i)
if not match:
out.append(text[i:])
break
out.append(text[i : match.start()])
i = match.end()
num, i = _read_tex_token(text, i)
den, i = _read_tex_token(text, i)
if num is None or den is None:
continue
num_s = _speak_operand(_verbalize_math(num))
den_s = _speak_operand(_verbalize_math(den))
out.append(f" {num_s} over {den_s} ")
return "".join(out)
def _replace_sqrt_once(text: str) -> str:
out: list[str] = []
i = 0
n = len(text)
while i < n:
j = text.find(r"\sqrt", i)
if j == -1 or (j + 5 < n and text[j + 5].isalpha()):
if j == -1:
out.append(text[i:])
break
out.append(text[i : j + 5])
i = j + 5
continue
out.append(text[i:j])
i = j + 5
i = _skip_ws(text, i)
root: str | None = None
if i < n and text[i] == "[":
close = text.find("]", i + 1)
if close != -1:
root = text[i + 1 : close]
i = close + 1
i = _skip_ws(text, i)
inner, i = _read_tex_token(text, i)
if inner is None:
continue
spoken = _speak_operand(_verbalize_math(inner))
if root is None or root.strip() in {"", "2"}:
out.append(f" square root of {spoken} ")
elif root.strip() == "3":
out.append(f" cube root of {spoken} ")
else:
root_s = _speak_operand(_verbalize_math(root))
out.append(f" {root_s} root of {spoken} ")
return "".join(out)
def _replace_binom_once(text: str) -> str:
out: list[str] = []
i = 0
n = len(text)
opener = re.compile(r"\\binom(?![a-zA-Z])")
while i < n:
match = opener.search(text, i)
if not match:
out.append(text[i:])
break
out.append(text[i : match.start()])
i = match.end()
top, i = _read_tex_token(text, i)
bot, i = _read_tex_token(text, i)
if top is None or bot is None:
continue
out.append(
f" {_speak_operand(_verbalize_math(top))} choose "
f"{_speak_operand(_verbalize_math(bot))} "
)
return "".join(out)
def _replace_limits_once(text: str) -> str:
out: list[str] = []
i = 0
n = len(text)
opener = re.compile(r"\\(" + "|".join(_LIMIT_HEAD) + r")(?![a-zA-Z])")
while i < n:
match = opener.search(text, i)
if not match:
out.append(text[i:])
break
out.append(text[i : match.start()])
i = match.end()
i = _skip_ws(text, i)
sub = None
sup = None
if i < n and text[i] == "_":
sub, i = _read_tex_token(text, i + 1)
i = _skip_ws(text, i)
if i < n and text[i] == "^":
sup, i = _read_tex_token(text, i + 1)
head = _LIMIT_HEAD[match.group(1)]
parts = [head]
if match.group(1) == "lim":
if sub:
parts.append("as")
parts.append(_verbalize_math(sub).strip())
if sup:
parts.append("to")
parts.append(_verbalize_math(sup).strip())
else:
if sub:
parts.append("from")
parts.append(_verbalize_math(sub).strip())
if sup:
parts.append("to")
parts.append(_verbalize_math(sup).strip())
out.append(" " + " ".join(p for p in parts if p) + " ")
return "".join(out)
def _speak_sup(inner: str) -> str:
token = inner.strip()
token = _replace_named_commands(token, {**_GREEK, **_OPERATORS, **_FUNCTIONS})
token = token.strip()
if token in {"2"}:
return " squared "
if token in {"3"}:
return " cubed "
if token in {"-1"}:
return " inverse "
if token in {"T", "t", "top", "intercal"}:
return " transpose "
if token in {"prime", "'"}:
return " prime "
if token in {"circ", "o", "\\circ"}:
return " degrees "
if token in {"*"}:
return " star "
return f" to the {token} "
def _verbalize_scripts(text: str) -> str:
out: list[str] = []
i = 0
n = len(text)
while i < n:
ch = text[i]
if ch in "^_" and not _is_escaped(text, i):
kind = ch
token, nxt = _read_tex_token(text, i + 1)
if token is None:
i += 1
continue
i = nxt
if kind == "^":
out.append(_speak_sup(token))
else:
spoken = _verbalize_math(token).strip() if "\\" in token else token.strip()
out.append(f" sub {spoken} ")
continue
out.append(ch)
i += 1
return "".join(out)
def _drop_unknown_commands(text: str) -> str:
out: list[str] = []
i = 0
n = len(text)
while i < n:
if text[i] == "\\" and i + 1 < n:
match = re.match(r"\\[a-zA-Z]+", text[i:])
if match:
i += match.end()
i = _skip_ws(text, i)
if i < n and text[i] == "{":
grp = _read_group(text, i)
if grp is not None:
inner, i = grp
out.append(inner)
continue
nxt = text[i + 1]
if nxt in "{}":
i += 2
continue
if nxt in "[]()|,.;!":
out.append(nxt)
i += 2
continue
if nxt in ",;! \\":
out.append(" ")
i += 2
continue
i += 2
continue
out.append(text[i])
i += 1
return "".join(out)
def _drop_braces(text: str) -> str:
return text.replace("{", " ").replace("}", " ")
def _verbalize_math(text: str) -> str:
"""Turn one math island's inner TeX into speakable words."""
if not text:
return ""
out = text.replace("&", " ")
out = out.replace(r"\\", ", ")
out = _replace_blackboard_sets(out)
out = _until_stable(_unwrap_style_once, out)
out = _until_stable(_replace_frac_once, out)
out = _until_stable(_replace_sqrt_once, out)
out = _until_stable(_replace_binom_once, out)
out = _until_stable(_replace_limits_once, out)
out = _replace_named_commands(out, {**_GREEK, **_OPERATORS, **_FUNCTIONS, **_SPACING_DROP})
out = _verbalize_scripts(out)
out = _drop_unknown_commands(out)
out = _drop_braces(out)
out = _PAD_PLUS_EQ.sub(r" \1 ", out)
out = _MULTI_SPACE.sub(" ", out)
return out.strip()
def _replace_unicode(text: str) -> str:
if not text:
return text
out = text
for src, spoken in _UNICODE_MATH.items():
if src in out:
out = out.replace(src, spoken)
return out
def _verbalize_loose_commands(text: str) -> str:
"""Convert leftover TeX commands in prose; never touch bare ``_`` / ``^``.
Windows paths are passed through even when nearby prose contains TeX.
"""
if "\\" not in text or not _LOOSE_TEX.search(text):
return text
def speak(segment: str) -> str:
out = _replace_blackboard_sets(segment)
out = _until_stable(_unwrap_style_once, out)
out = _until_stable(_replace_frac_once, out)
out = _until_stable(_replace_sqrt_once, out)
out = _until_stable(_replace_binom_once, out)
out = _until_stable(_replace_limits_once, out)
# Unknown commands in prose may be path segments or product names.
# Only an explicit math island is safe to clean up destructively.
return _replace_named_commands(out, {**_GREEK, **_OPERATORS, **_FUNCTIONS, **_SPACING_DROP})
parts: list[str] = []
offset = 0
for match in _WINDOWS_PATH.finditer(text):
parts.append(speak(text[offset : match.start()]))
parts.append(match.group())
offset = match.end()
parts.append(speak(text[offset:]))
return "".join(parts)
def _emit_island(inner: str, *, math_speak: bool) -> str:
return _verbalize_math(inner) if math_speak else inner
def verbalize_latex_for_speech(
text: str, *, math_speak: bool = True, prose_transform: Callable[[str], str] | None = None
) -> str:
"""Replace math islands with speakable prose, or just unwrap delimiters.
``math_speak=True`` (default) verbalizes fractions, powers, Greek, and
operators. ``math_speak=False`` still strips ``$`` / ``$$`` / ``\\(``
wrappers so TTS never says "dollar", but leaves the inner TeX as-is.
Bare underscores outside math are preserved (``file_name`` stays intact).
Leftover ``$`` from broken markup is dropped. An optional prose transform
cleans surrounding Markdown while leaving each math island intact.
"""
if not text:
return ""
if "$" not in text and "\\" not in text:
spoken = _replace_unicode(text) if math_speak else text
return prose_transform(spoken) if prose_transform else spoken
out: list[str] = []
prose: list[str] = []
def flush_prose() -> None:
segment = "".join(prose)
out.append(prose_transform(segment) if prose_transform else segment)
prose.clear()
def append_island(inner: str) -> None:
flush_prose()
out.extend((" ", _emit_island(inner, math_speak=math_speak), " "))
i = 0
n = len(text)
while i < n:
if text.startswith("$$", i) and not _is_escaped(text, i):
end = text.find("$$", i + 2)
if end != -1:
append_island(text[i + 2 : end])
i = end + 2
continue
if text.startswith("\\[", i):
end = text.find("\\]", i + 2)
if end != -1:
append_island(text[i + 2 : end])
i = end + 2
continue
if text.startswith("\\(", i):
end = text.find("\\)", i + 2)
if end != -1:
append_island(text[i + 2 : end])
i = end + 2
continue
begin = _BEGIN_ENV.match(text, i)
if begin and begin.group(1) in _MATH_ENVS:
env = begin.group(1)
end_tag = f"\\end{{{env}}}"
end = text.find(end_tag, begin.end())
if end != -1:
append_island(text[begin.end() : end])
i = end + len(end_tag)
continue
if text[i] == "$" and not _is_escaped(text, i):
j = i + 1
while j < n:
if text[j] == "\n":
j = -1
break
if text[j] == "$" and not _is_escaped(text, j):
break
j += 1
if j > i:
append_island(text[i + 1 : j])
i = j + 1
continue
prose.append(text[i])
i += 1
flush_prose()
spoken = "".join(out)
if math_speak:
spoken = _verbalize_loose_commands(spoken)
spoken = _replace_unicode(spoken)
spoken = _LEFTOVER_DOLLAR.sub("", spoken)
return spoken
__all__ = ["verbalize_latex_for_speech"]