think_scrubber.py 9.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187
  1. """Stateful scrubber for reasoning/thinking blocks in streamed assistant text.
  2. The regex ``_strip_think_blocks`` is correct for a complete string but, run per-delta, erases an
  3. opening ``<think>`` that arrives alone, so downstream state machines leak reasoning. This class
  4. holds partial tags at delta boundaries until resolved; ``flush()`` releases held-back prose that
  5. was not a tag; ``reset()`` at the top of each turn. An open tag only starts a block at a block
  6. boundary (stream start / after a newline / whitespace-only line so far), so prose that *mentions*
  7. ``<think>`` is not suppressed; closed pairs are always suppressed (intentional).
  8. """
  9. from __future__ import annotations
  10. import re
  11. from typing import Tuple
  12. __all__ = ["THINK_CLOSE_TAGS", "THINK_OPEN_TAGS", "THINK_TAG_NAMES", "StreamingThinkScrubber"]
  13. # The one list of model reasoning tag names. Every surface that hides reasoning (this scrubber,
  14. # the CLI stream filter, the gateway stream filter, the final-response regex stripper) binds to
  15. # these; a tag added here is covered everywhere. Consumers match case-insensitively, so the
  16. # literal tags are lowercase. The CJK names cover models (MiniMax-M3) that emit Chinese reasoning
  17. # tags: 思考 (think), 反思 (reflect), 推理 (reason), 推敲 (deliberate).
  18. THINK_TAG_NAMES: tuple[str, ...] = (
  19. "think", "thinking", "reasoning", "thought", "REASONING_SCRATCHPAD",
  20. "思考", "反思", "推理", "推敲",
  21. )
  22. THINK_OPEN_TAGS: tuple[str, ...] = tuple(f"<{name.lower()}>" for name in THINK_TAG_NAMES)
  23. THINK_CLOSE_TAGS: tuple[str, ...] = tuple(f"</{name.lower()}>" for name in THINK_TAG_NAMES)
  24. class StreamingThinkScrubber:
  25. """Stateful scrubber for streaming reasoning/thinking blocks.
  26. State: ``_in_block`` (inside an open block; text discarded), ``_buf`` (held-back partial-tag
  27. tail), ``_last_emitted_ended_newline`` (True iff the last emission ended with ``\\n`` or nothing
  28. was emitted yet — decides whether an open tag at buffer position 0 sits at a block boundary).
  29. """
  30. # Literal tags so the hot path does string ops, not regex per feed().
  31. _OPEN_TAGS: tuple[str, ...] = THINK_OPEN_TAGS
  32. _CLOSE_TAGS: tuple[str, ...] = THINK_CLOSE_TAGS
  33. _ALL_TAGS: tuple[str, ...] = _OPEN_TAGS + _CLOSE_TAGS
  34. _MAX_TAG_LEN: int = max(len(tag) for tag in _ALL_TAGS)
  35. # Orphan close tag plus trailing whitespace (matches _strip_think_blocks case 3).
  36. _ORPHAN_CLOSE_RE = re.compile(
  37. "(?:" + "|".join(re.escape(t) for t in _CLOSE_TAGS) + r")[ \t\n\r]*", re.IGNORECASE
  38. )
  39. def __init__(self) -> None:
  40. self.reset()
  41. def reset(self) -> None:
  42. """Reset all state. Call at the top of every new turn."""
  43. self._in_block: bool = False
  44. self._buf: str = ""
  45. self._last_emitted_ended_newline: bool = True
  46. # Reasoning text the most recent feed() stripped from inside think blocks (tags excluded).
  47. self.last_hidden: str = ""
  48. def _emit(self, out: list[str], text: str) -> None:
  49. """Append visible prose to *out* (orphan close tags stripped) and track the newline flag."""
  50. text = self._strip_orphan_close_tags(text)
  51. if text:
  52. out.append(text)
  53. self._last_emitted_ended_newline = text.endswith("\n")
  54. def feed(self, text: str) -> str:
  55. """Feed one delta; return the scrubbed visible portion ("" when it is all reasoning or held back)."""
  56. self.last_hidden = ""
  57. if not text:
  58. return ""
  59. buf = self._buf + text
  60. self._buf = ""
  61. out: list[str] = []
  62. hidden: list[str] = []
  63. while buf:
  64. if self._in_block:
  65. close_idx, close_len = self._find_first_tag(buf, self._CLOSE_TAGS)
  66. if close_idx == -1:
  67. # No close yet: hold back a possible partial close-tag prefix; the rest is reasoning.
  68. hidden.append(self._hold_partial(buf, self._CLOSE_TAGS))
  69. break
  70. hidden.append(buf[:close_idx])
  71. buf = buf[close_idx + close_len:]
  72. self._in_block = False
  73. continue
  74. # Priority 1: closed <tag>X</tag> pair anywhere (even inline pairs are almost
  75. # certainly leaked reasoning). Priority 2: unterminated open tag at a block
  76. # boundary (gated so prose mentioning '<think>' isn't over-stripped). Earliest wins.
  77. pair = self._find_earliest_closed_pair(buf)
  78. open_idx, open_len = self._find_open_at_boundary(buf, out)
  79. if pair is not None and (open_idx == -1 or pair[0] <= open_idx):
  80. self._emit(out, buf[:pair[0]])
  81. # Pair tags are exact ``<name>``/``</name>``: inner text sits between them.
  82. hidden.append(buf[buf.index(">", pair[0]) + 1:buf.rindex("<", pair[0], pair[1])])
  83. buf = buf[pair[1]:]
  84. continue
  85. if open_idx != -1:
  86. self._emit(out, buf[:open_idx])
  87. self._in_block = True
  88. buf = buf[open_idx + open_len:]
  89. continue
  90. # No resolvable tag: hold back any partial-tag prefix at the tail
  91. # so a tag split across deltas isn't missed, then emit the rest.
  92. self._emit(out, self._hold_partial(buf, self._ALL_TAGS))
  93. break
  94. self.last_hidden = "".join(hidden)
  95. return "".join(out)
  96. def _hold_partial(self, buf: str, tags: tuple[str, ...]) -> str:
  97. """Move a trailing partial-tag prefix of *buf* into ``_buf``; return the remainder."""
  98. held = self._max_partial_suffix(buf, tags)
  99. self._buf = buf[-held:] if held else ""
  100. return buf[:-held] if held else buf
  101. def flush(self) -> str:
  102. """End-of-stream flush: inside an unterminated block the held-back content is discarded (leaking
  103. partial reasoning is worse than a truncated answer), otherwise the tail is emitted verbatim.
  104. Always resets the boundary flag — intra-turn retries flush then stream again without ``reset()``,
  105. and a stale False flag made the new stream's opening ``<think>`` look mid-line."""
  106. tail = "" if self._in_block else self._buf
  107. self._buf = ""
  108. self._in_block = False
  109. self._last_emitted_ended_newline = True
  110. return self._strip_orphan_close_tags(tail) if tail else ""
  111. # ── internal helpers ───────────────────────────────────────────────
  112. @staticmethod
  113. def _find_first_tag(buf: str, tags: tuple[str, ...]) -> tuple[int, int]:
  114. """Return (earliest_index, tag_length) over *tags* (case-insensitive), or (-1, 0)."""
  115. buf_lower = buf.lower()
  116. hits = [(idx, len(tag)) for tag in tags if (idx := buf_lower.find(tag)) != -1]
  117. return min(hits) if hits else (-1, 0)
  118. def _find_earliest_closed_pair(self, buf: str):
  119. """(start_idx, end_idx) of the earliest ``<tag>...</tag>`` pair (non-greedy, case-insensitive), else None."""
  120. buf_lower = buf.lower()
  121. pairs = []
  122. for open_tag, close_tag in zip(self._OPEN_TAGS, self._CLOSE_TAGS):
  123. open_idx = buf_lower.find(open_tag)
  124. close_idx = buf_lower.find(close_tag, open_idx + len(open_tag)) if open_idx != -1 else -1
  125. if close_idx != -1:
  126. pairs.append((open_idx, close_idx + len(close_tag)))
  127. return min(pairs) if pairs else None
  128. def _find_open_at_boundary(self, buf: str, already_emitted: list[str]) -> tuple[int, int]:
  129. """Return the earliest block-boundary open-tag (idx, len), or (-1, 0)."""
  130. buf_lower = buf.lower()
  131. hits = []
  132. for tag in self._OPEN_TAGS:
  133. idx = buf_lower.find(tag)
  134. while idx != -1 and not self._is_block_boundary(buf, idx, already_emitted):
  135. idx = buf_lower.find(tag, idx + 1)
  136. if idx != -1:
  137. hits.append((idx, len(tag)))
  138. return min(hits) if hits else (-1, 0)
  139. def _is_block_boundary(self, buf: str, idx: int, already_emitted: list[str]) -> bool:
  140. """True iff *idx* is a block boundary: position 0 after a newline-terminated (or no) prior emission,
  141. or any position whose preceding text on the current line is whitespace-only (when no newline
  142. precedes it in *buf*, the prior emission must also have ended with a newline)."""
  143. prior_newline = already_emitted[-1].endswith("\n") if already_emitted else self._last_emitted_ended_newline
  144. if idx == 0:
  145. return prior_newline
  146. preceding = buf[:idx]
  147. last_nl = preceding.rfind("\n")
  148. return (prior_newline if last_nl == -1 else True) and preceding[last_nl + 1:].strip() == ""
  149. @classmethod
  150. def _max_partial_suffix(cls, buf: str, tags: tuple[str, ...]) -> int:
  151. """Longest buf-suffix that is a strict prefix of any tag (full matches are real tags, handled elsewhere)."""
  152. buf_lower = buf.lower()
  153. for i in range(min(len(buf_lower), cls._MAX_TAG_LEN - 1), 0, -1):
  154. suffix = buf_lower[-i:]
  155. if any(len(tag) > i and tag.startswith(suffix) for tag in tags):
  156. return i
  157. return 0
  158. @classmethod
  159. def _strip_orphan_close_tags(cls, text: str) -> str:
  160. """Remove close tags with no matching open (always noise) plus trailing whitespace."""
  161. return cls._ORPHAN_CLOSE_RE.sub("", text) if "</" in text else text