Skip to content

Run frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦

C

refactor(server): report what each text stage deleted as a span map

monotophic68cb5e6a310f
diff --git a/c/openai_server.py b/c/openai_server.py
index 76b4a904..c9a93a9c 100644
--- a/c/openai_server.py
+++ b/c/openai_server.py
@@ -376,6 +376,100 @@ _SALVAGE = os.environ.get("COLI_TOOL_SALVAGE", "0") == "1"
_TOOL_FALLBACK = os.environ.get("COLI_TOOL_FALLBACK", "0") == "1"
+# ---- raw-stream span maps ---------------------------------------------------------------
+# Every transformation between the engine's raw stream and the string a client receives is
+# a DELETION: the stop filter withholds a matched sequence, the thinking split routes each
+# character into one bucket or the other, the tool-call parse removes box syntax. None
+# writes a character its input did not hold and none reorders, so a stage can report what
+# it did as an ordered list of surviving intervals -- [(in_start, in_end, out_start), ...],
+# monotonic and non-overlapping -- in ITS OWN INPUT's coordinates. Output positions are
+# assigned in input order with no gaps, which keeps the image of a contiguous range
+# contiguous and composition associative.
+
+def _append_span(spans, in_start, in_end, out_start):
+ """Append one surviving interval, merging it into the previous one when the two are
+ adjacent on both sides so the map stays canonical."""
+ if in_end <= in_start:
+ return
+ if spans:
+ previous_start, previous_end, previous_out = spans[-1]
+ if previous_end == in_start and previous_out + (previous_end - previous_start) == out_start:
+ spans[-1] = (previous_start, in_end, previous_out)
+ return
+ spans.append((in_start, in_end, out_start))
+
+
+def _cut_span_map(length, cuts):
+ """The deletion map for removing `cuts` -- possibly overlapping [start, end) ranges --
+ from a string of `length` characters.
+
+ The cuts are sorted here rather than required to arrive sorted: every caller today
+ produces them in order, and an out-of-order list silently produced a wrong map, which
+ is the kind of precondition a later caller discovers the expensive way."""
+ spans, cursor, out = [], 0, 0
+ for start, end in sorted(cuts):
+ if start > cursor:
+ _append_span(spans, cursor, start, out)
+ out += start - cursor
+ cursor = max(cursor, end)
+ if cursor < length:
+ _append_span(spans, cursor, length, out)
+ return spans
+
+
+def _apply_cuts(text, cuts):
+ """`(remaining text, deletion map)` for removing `cuts` from `text`. One step of a
+ multi-step stage: the caller composes the steps' maps in the same order it applies
+ them, because each step's cuts are found in the text the previous step produced."""
+ spans = _cut_span_map(len(text), cuts)
+ return "".join(text[start:end] for start, end, _out in spans), spans
+
+
+def _compose_span_maps(first, second):
+ """Chain a stage's map with the map of the stage that consumes its output: `first` is
+ X -> Y, `second` is Y -> Z, and the result is X -> Z."""
+ composed, index = [], 0
+ for in_start, in_end, out_start in first:
+ middle_end = out_start + (in_end - in_start)
+ while index < len(second) and second[index][1] <= out_start:
+ index += 1 # `first` is monotonic in Y, so this never rewinds
+ probe = index
+ while probe < len(second) and second[probe][0] < middle_end:
+ middle_start, middle_stop, final_out = second[probe]
+ low, high = max(out_start, middle_start), min(middle_end, middle_stop)
+ if low < high:
+ _append_span(composed, in_start + (low - out_start), in_start + (high - out_start),
+ final_out + (low - middle_start))
+ probe += 1
+ return composed
+
+
+def _project_point(span_map, position):
+ """How many input characters strictly before `position` survive `span_map`."""
+ low, high = 0, len(span_map)
+ while low < high:
+ middle = (low + high) // 2
+ if span_map[middle][0] <= position:
+ low = middle + 1
+ else:
+ high = middle
+ if low == 0:
+ return 0
+ in_start, in_end, out_start = span_map[low - 1]
+ return out_start + min(position, in_end) - in_start
+
+
+def _project_span(span_map, start, end):
+ """Where input range [start, end) lands in the stage's output, or None when every
+ character of it was deleted.
+
+ One interval, not a list: a deletion map assigns output positions in input order with
+ no gaps, so even a deletion inside the range leaves a contiguous image -- the survivors
+ on either side of the hole become adjacent once the hole is gone."""
+ low, high = _project_point(span_map, start), _project_point(span_map, end)
+ return (low, high) if high > low else None
+
+
def _tool_choice_name(tool_choice):
"""The tool name a dict `tool_choice` forces, or None.
@@ -467,9 +561,63 @@ def _unclosed_tail(reply, tools):
return inner if inner.strip() in declared else None
+def _marker_cuts(text, marker):
+ """Every non-overlapping occurrence of `marker`, left to right -- what
+ str.replace(marker, "") removes, found as ranges instead of applied as a rewrite."""
+ if not marker:
+ return [] # find("") never advances past `index`
+ cuts, index = [], text.find(marker)
+ while index >= 0:
+ cuts.append((index, index + len(marker)))
+ index = text.find(marker, index + len(marker))
+ return cuts
+
+
+def _tool_call_content_spans(reply, tail):
+ """parse_tool_calls' content derivation as `(content, box_map, content_map)`, both maps
+ in `reply`'s own coordinates.
+
+ Every step is a deletion or a slice, so the whole derivation is one composed map. The
+ steps are applied in order and composed in the same order, because each step's cuts are
+ found in the text the previous step produced. `box_map` stops after the tool-call
+ removals, which is what tells a character consumed as tool-call syntax apart from one
+ consumed as thinking markup.
+
+ Both maps are None for inkling, whose marker stripping is not modelled here: an inkling
+ engine does not support the numeric logprobs channel, so no logprobs object can reach
+ this text to be aligned."""
+ cuts = [(match.start(), match.end()) for match in _BOX_RE.finditer(reply)]
+ text, box_map = _apply_cuts(reply, cuts)
+ if tail is not None: # drop the recovered tail from the visible content
+ text, step = _apply_cuts(text, [(text.rindex(BOX_START), len(text))])
+ box_map = _compose_span_maps(box_map, step)
+ content_map = box_map
+ if ARCH == "inkling":
+ text = strip_inkling_markers(text) # thinking is reasoning, not answer
+ box_map = content_map = None
+ if THINK_CLOSE in text:
+ text, step = _apply_cuts(text, [(0, text.index(THINK_CLOSE) + len(THINK_CLOSE))])
+ content_map = content_map and _compose_span_maps(content_map, step)
+ for marker in (THINK_OPEN, THINK_CLOSE):
+ text, step = _apply_cuts(text, _marker_cuts(text, marker))
+ content_map = content_map and _compose_span_maps(content_map, step)
+ stripped = text.strip()
+ head = len(text) - len(text.lstrip())
+ text, step = _apply_cuts(text, [(0, head), (head + len(stripped), len(text))])
+ content_map = content_map and _compose_span_maps(content_map, step)
+ return text, box_map, content_map
+
+
def parse_tool_calls(reply, tools=None):
"""Return (content, tool_calls). Strict GLM parse; optional de-mangler (COLI_TOOL_SALVAGE=1)
rescues malformed int4 output by mapping a lone payload onto the tool's primary parameter."""
+ content, calls, _box_map, _content_map = parse_tool_calls_spans(reply, tools)
+ return content, calls
+
+
+def parse_tool_calls_spans(reply, tools=None):
+ """parse_tool_calls plus the tool-call stage's maps: `(content, tool_calls, box_map,
+ content_map)`. One implementation, so the maps cannot drift from the text."""
param_order = _tool_param_order(tools)
param_types = _tool_param_types(tools)
calls, salvaged = [], []
@@ -512,14 +660,7 @@ def parse_tool_calls(reply, tools=None):
sys.stderr.write("[api] tools declared and tool-call markers present, but no call "
"parsed -- output may be quantization-mangled; try COLI_TOOL_SALVAGE=1\n")
sys.stderr.flush()
- text = _BOX_RE.sub("", reply)
- if tail is not None: # drop the recovered tail from the visible content
- text = text[:text.rindex(BOX_START)]
- if ARCH == "inkling":
- text = strip_inkling_markers(text) # thinking is reasoning, not answer
- if THINK_CLOSE in text:
- text = text.split(THINK_CLOSE, 1)[1]
- text = text.replace(THINK_OPEN, "").replace(THINK_CLOSE, "")
+ text, box_map, content_map = _tool_call_content_spans(reply, tail)
if calls:
dm, rec = len(salvaged), (1 if tail is not None else 0)
sys.stderr.write("[api] tool-calls: %d total, %d strict, %d unclosed-recovered, "
@@ -528,7 +669,7 @@ def parse_tool_calls(reply, tools=None):
"CLEAN" if dm == 0 and rec == 0 else "RECOVERED",
(" -> " + ", ".join(salvaged)) if dm else ""))
sys.stderr.flush()
- return text.strip(), calls
+ return text, calls, box_map, content_map
# ---- DeepSeek V4 tool calling (DSML) -------------------------------------------------------
@@ -690,18 +831,30 @@ def parse_dsv41_tool_calls(reply):
def parse_arch_tool_calls(reply, tools, tool_reply=None):
"""Architecture-appropriate tool-call parser. Returns (content, tool_calls)."""
+ content, calls, _box_map, _content_map = parse_arch_tool_calls_spans(reply, tools, tool_reply)
+ return content, calls
+
+
+def parse_arch_tool_calls_spans(reply, tools, tool_reply=None):
+ """parse_arch_tool_calls plus the tool-call stage's maps: `(content, tool_calls,
+ box_map, content_map)`.
+
+ Only the glm/default parser reports maps; the others return None for both. A request
+ that opted into the numeric logprobs channel is refused with a named 400 on any other
+ architecture, so no reply reaching those branches can carry a logprobs object for a
+ map to align."""
if ARCH == "deepseek_v4":
- return parse_dsv4_tool_calls(reply)
+ return parse_dsv4_tool_calls(reply) + (None, None)
if ARCH == "deepseek_v41":
- return parse_dsv41_tool_calls(reply)
+ return parse_dsv41_tool_calls(reply) + (None, None)
if ARCH == "kimi":
if tool_reply is not None:
_sideband_text, calls = parse_k3_tool_calls(tool_reply, tools)
- return reply.strip(), calls
- return parse_k3_tool_calls(reply, tools) # compatibility with pre-#1147 engines
+ return reply.strip(), calls, None, None
+ return parse_k3_tool_calls(reply, tools) + (None, None) # pre-#1147 engines
if ARCH == "qwen38":
- return parse_qwen38_tool_calls(reply, tools)
- return parse_tool_calls(reply, tools)
+ return parse_qwen38_tool_calls(reply, tools) + (None, None)
+ return parse_tool_calls_spans(reply, tools)
def _tool_stream_markers():
@@ -2636,7 +2789,15 @@ def starts_in_reasoning(enable_thinking, add_generation_prompt=True):
class ThinkingStreamSplit:
- """Split GLM's reasoning marker without leaking markers across stream chunks."""
+ """Split GLM's reasoning marker without leaking markers across stream chunks.
+
+ `thinking_spans` and `text_spans` are this stage's maps, in its own input's
+ coordinates. Every character is routed to exactly one bucket or is marker syntax
+ routed to neither, and which bucket decides which array a token record belongs to.
+
+ Unlike the stop filter's map these are built unconditionally: they cost two list
+ appends and a merge per emitted run, which is not worth a flag and a second code path
+ through the splitter."""
MARKERS = (THINK_OPEN, THINK_CLOSE)
def __init__(self, on_thinking, on_text, on_thinking_end=None, initial_thinking=True):
@@ -2648,10 +2809,19 @@ class ThinkingStreamSplit:
# the splitter must start in text mode or it would file the whole answer as reasoning.
self.thinking = initial_thinking
self.buf = ""
+ self.thinking_spans = []
+ self.text_spans = []
+ self.consumed = 0 # input characters resolved, marker or not
def _emit(self, text):
if text:
(self.on_thinking if self.thinking else self.on_text)(text)
+ spans = self.thinking_spans if self.thinking else self.text_spans
+ _append_span(spans, self.consumed, self.consumed + len(text),
+ spans[-1][2] + (spans[-1][1] - spans[-1][0]) if spans else 0)
+ # Every emitted run is a prefix of `buf`, so the run's input start is always
+ # `consumed` and advancing it here keeps that true for the next one.
+ self.consumed += len(text)
def feed(self, chunk):
self.buf += chunk
@@ -2662,6 +2832,7 @@ class ThinkingStreamSplit:
offset, marker = min(hits, key=lambda hit: hit[0])
self._emit(self.buf[:offset])
self.buf = self.buf[offset + len(marker):]
+ self.consumed += len(marker) # the marker itself reaches neither bucket
if marker == THINK_CLOSE and self.thinking:
self.thinking = False
if self.on_thinking_end:
@@ -2687,13 +2858,21 @@ class ThinkingStreamSplit:
def split_thinking_reply(text, enable_thinking=True, add_generation_prompt=True):
"""Return the marker-free (thinking, answer) portions of one GLM reply."""
+ thinking, answer, _spans = split_thinking_reply_spans(text, enable_thinking,
+ add_generation_prompt)
+ return thinking, answer
+
+
+def split_thinking_reply_spans(text, enable_thinking=True, add_generation_prompt=True):
+ """split_thinking_reply plus the split's maps: `(thinking, answer, (thinking_map,
+ answer_map))`, both in `text`'s own coordinates."""
thinking, answer = [], []
split = ThinkingStreamSplit(thinking.append, answer.append,
initial_thinking=starts_in_reasoning(enable_thinking,
add_generation_prompt))
split.feed(text)
split.finish()
- return "".join(thinking), "".join(answer)
+ return "".join(thinking), "".join(answer), (split.thinking_spans, split.text_spans)
def _anthropic_block_text(blocks, param):
@@ -2936,8 +3115,13 @@ def stop_policy(body, chat):
class StopFilter:
- """Stream text without exposing a full or partial stop sequence."""
- def __init__(self, sequences, emit, ignore_leading=False):
+ """Stream text without exposing a full or partial stop sequence.
+
+ `spans` is this stage's map: the intervals of the raw stream -- the concatenation of
+ everything ever fed -- that reached `emit`, each with where it landed in the emitted
+ text. It is built only when `track_spans` is set, so a request that never asked for
+ per-token logprobs pays nothing for it."""
+ def __init__(self, sequences, emit, ignore_leading=False, track_spans=False):
self.sequences = tuple(sequences)
self.emit = emit
self.ignore_leading = ignore_leading
@@ -2945,10 +3129,19 @@ class StopFilter:
self.matched = None
self.useful_content_seen = False
self.leading_matches_ignored = 0
-
- def _emit(self, text):
+ self.track_spans = track_spans
+ self.spans = []
+ # Raw offset of self.pending[0], equivalently of feed()'s `text[0]`. Everything the
+ # filter drops is accounted for by advancing this without emitting.
+ self.raw_base = 0
+ self.emitted = 0
+
+ def _emit(self, text, raw_start):
if text:
self.emit(text)
+ if self.track_spans:
+ _append_span(self.spans, raw_start, raw_start + len(text), self.emitted)
+ self.emitted += len(text)
if text.strip():
self.useful_content_seen = True
@@ -2956,6 +3149,7 @@ class StopFilter:
if self.matched is not None:
return
text = self.pending + chunk
+ base = self.raw_base
self.pending = ""
while True:
match = None
@@ -2972,11 +3166,16 @@ class StopFilter:
and not prefix.strip()):
self.leading_matches_ignored += 1
text = text[offset + len(sequence):]
+ # The ignored marker and the blank prefix in front of it never reach the
+ # client, so no span covers them and a record inside one resolves to
+ # "not emitted" instead of derailing the alignment.
+ base += offset + len(sequence)
if not text:
+ self.raw_base = base
return
continue
self.matched = sequence
- self._emit(prefix)
+ self._emit(prefix, base)
return
hold = 0
@@ -2987,12 +3186,13 @@ class StopFilter:
hold = size
flush = len(text) - hold
if flush:
- self._emit(text[:flush])
+ self._emit(text[:flush], base)
self.pending = text[flush:]
+ self.raw_base = base + flush
def finish(self):
if self.matched is None and self.pending:
- self._emit(self.pending)
+ self._emit(self.pending, self.raw_base)
self.pending = ""
def stopped(self):
diff --git a/c/tests/test_openai_server.py b/c/tests/test_openai_server.py
index afe7b80b..1c5e41ff 100644
--- a/c/tests/test_openai_server.py
+++ b/c/tests/test_openai_server.py
@@ -16,7 +16,7 @@ from urllib.request import Request, urlopen
from pathlib import Path
from openai_server import (APIError, APIHandler, APIServer, ClientCancelled,
- CONTINUATION_FAMILIES,
+ CONTINUATION_FAMILIES, _marker_cuts,
DEFAULT_CHAT_STOP_SEQUENCES, END, GenerationScheduler,
READY, Engine, InklingStreamSplit, StopFilter, ThinkingStreamSplit,
_engine_error, _image_bytes_from_url, cap_for_arch, conversation_cache_slot, model_arch,
@@ -28,7 +28,10 @@ from openai_server import (APIError, APIHandler, APIServer, ClientCancelled,
render_chat_qwen38, render_chat_v4, render_chat_dsv41,
_dsv4_tool_calls, serve,
resolve_generation_prompt, split_thinking_reply,
- starts_in_reasoning,
+ split_thinking_reply_spans, starts_in_reasoning,
+ parse_tool_calls_spans, parse_arch_tool_calls_spans,
+ THINK_OPEN, THINK_CLOSE,
+ _compose_span_maps, _cut_span_map, _project_span,
stop_policy, tune_child_env)
@@ -547,6 +550,244 @@ class StopFilterTest(unittest.TestCase):
self.assertEqual(stop_filter.matched, "STOP")
+class SpanMapPrimitivesTest(unittest.TestCase):
+ """The stage-map algebra, on literal maps written out by hand -- no stage builds any of
+ these, so nothing here can be satisfied by the same code it polices."""
+
+ def test_cut_map_records_the_survivors_around_each_cut(self):
+ # "abcXYdef" minus [3, 5): two survivors, and the second one's output position is 3
+ # because exactly three characters precede it.
+ self.assertEqual(_cut_span_map(8, [(3, 5)]), [(0, 3, 0), (5, 8, 3)])
+
+ def test_adjacent_cuts_leave_one_merged_survivor_not_two(self):
+ # "abcd" minus [1, 2) and [2, 3) is one span on each side, never two abutting ones.
+ self.assertEqual(_cut_span_map(4, [(1, 2), (2, 3)]), [(0, 1, 0), (3, 4, 1)])
+
+ def test_composition_chains_two_stages_into_one_map(self):
+ # Stage one deletes "XY" from "abcXYdef" and hands "abcdef" on; stage two deletes
+ # "cd" from that, leaving "abef". Composed, the map speaks the original string's
+ # coordinates: 'a','b' at 0,1 and 'e','f' at 6,7.
+ first = [(0, 3, 0), (5, 8, 3)]
+ second = [(0, 2, 0), (4, 6, 2)]
+ self.assertEqual(_compose_span_maps(first, second), [(0, 2, 0), (6, 8, 2)])
+
+ def test_composition_is_associative_over_three_stages(self):
+ first, second, third = [(0, 3, 0), (5, 8, 3)], [(0, 2, 0), (4, 6, 2)], [(1, 4, 0)]
+ self.assertEqual(_compose_span_maps(_compose_span_maps(first, second), third),
+ _compose_span_maps(first, _compose_span_maps(second, third)))
+
+ def test_projection_of_a_fully_deleted_range_is_none_not_zero_zero(self):
+ # The distinction a prefix walk never makes: "deleted" is not "at offset 0".
+ self.assertIsNone(_project_span([(0, 2, 0), (6, 8, 2)], 3, 5))
+
+ def test_projection_spans_a_hole_because_survivors_close_up(self):
+ # Input [1, 7) covers 'b' (survives at 1) and 'e' (survives at 2) with the deleted
+ # middle between them: the image is the contiguous [1, 3).
+ self.assertEqual(_project_span([(0, 2, 0), (6, 8, 2)], 1, 7), (1, 3))
+
+ def test_cuts_out_of_order_produce_the_map_their_deletion_does(self):
+ # The map is the deletion, whatever order the ranges arrive in. Walking an
+ # unordered list as if it were sorted produces a map no deletion corresponds to,
+ # silently, and every stage downstream then reads the wrong coordinates.
+ text = "abcXYdefZW"
+ for cuts in ([(3, 5), (8, 10)], [(8, 10), (3, 5)]):
+ with self.subTest(cuts=cuts):
+ spans = _cut_span_map(len(text), cuts)
+ self.assertEqual(spans, [(0, 3, 0), (5, 8, 3)])
+ self.assertEqual("".join(text[a:b] for a, b, _o in spans), "abcdef")
+
+ def test_an_empty_marker_yields_no_cuts(self):
+ # `str.find("")` returns the cursor forever, so a marker that is somehow empty
+ # would spin rather than fail. Unreachable today -- both markers are non-empty
+ # module constants -- and the guard is one line.
+ self.assertEqual(_marker_cuts("abc", ""), [])
+ self.assertEqual(_marker_cuts("abcabc", "bc"), [(1, 3), (4, 6)])
+
+ def test_projection_clamps_a_range_that_runs_off_the_end(self):
+ # Records outlive the map: after a stop match the engine keeps sending frames the
+ # stop filter never sees, and those must project to nothing.
+ self.assertEqual(_project_span([(0, 3, 0)], 2, 9), (2, 3))
+ self.assertIsNone(_project_span([(0, 3, 0)], 4, 9))
+
+
+class StopFilterSpanAccountingTest(unittest.TestCase):
+ """The stop filter's map, with its own oracle: every expected span below is written out
+ by hand from the chunk sequence, never read back from the filter."""
+
+ def test_normal_flush_spans_the_characters_it_released(self):
+ # "one S" holds back the "S" (a live prefix of "STOP"); the next chunk resolves it.
+ # Both flushes are one contiguous run of the raw stream, so the canonical map is
+ # one span covering "one Swo", not two abutting ones.
+ output = []
+ stop_filter = StopFilter(("STOP",), output.append, track_spans=True)
+ stop_filter.feed("one S")
+ self.assertEqual(stop_filter.spans, [(0, 4, 0)])
+ stop_filter.feed("wo")
+ stop_filter.finish()
+ self.assertEqual("".join(output), "one Swo")
+ self.assertEqual(stop_filter.spans, [(0, 7, 0)])
+
+ def test_finish_spans_the_pending_tail_it_releases(self):
+ # "ST" is still held when the engine stops, so the map must grow at finish().
+ output = []
+ stop_filter = StopFilter(("STOP",), output.append, track_spans=True)
+ stop_filter.feed("tail ST")
+ self.assertEqual(stop_filter.spans, [(0, 5, 0)])
+ stop_filter.finish()
+ self.assertEqual("".join(output), "tail ST")
+ self.assertEqual(stop_filter.spans, [(0, 7, 0)])
+
+ def test_ignored_leading_marker_is_a_hole_in_the_map(self):
+ # "<|user|>" occupies raw [0, 8) and reaches no one, so the map starts at 8 and
+ # "Hello world" lands at output 0. A consumer reading this cannot conclude that
+ # record 0 was emitted.
+ output = []
+ stop_filter = StopFilter(("<|user|>",), output.append, ignore_leading=True,
+ track_spans=True)
+ for chunk in ("<|user|>", "Hello", " world"):
+ stop_filter.feed(chunk)
+ stop_filter.finish()
+ self.assertEqual("".join(output), "Hello world")
+ self.assertEqual(stop_filter.spans, [(8, 19, 0)])
+
+ def test_matched_stop_spans_only_the_prefix_it_emitted(self):
+ # "He" then "llo" against stop "lo" emits "Hel" and stops. Raw "Hello" is five
+ # characters; only [0, 3) was ever released.
+ output = []
+ stop_filter = StopFilter(("lo",), output.append, track_spans=True)
+ for chunk in ("He", "llo", "X"):
+ stop_filter.feed(chunk)
+ stop_filter.finish()
+ self.assertEqual("".join(output), "Hel")
+ self.assertEqual(stop_filter.matched, "lo")
+ self.assertEqual(stop_filter.spans, [(0, 3, 0)])
+
+ def test_stop_split_across_two_feeds_closes_the_map_at_the_match(self):
+ # The sequence arrives as "S" / "TO" / "P": the filter holds a growing partial
+ # prefix across three calls and must not count the held characters as emitted. Raw
+ # is "answer STOPignored" (18 characters); the map ends at 7.
+ output = []
+ stop_filter = StopFilter(("STOP",), output.append, track_spans=True)
+ for chunk in ("answer S", "TO", "Pignored"):
+ stop_filter.feed(chunk)
+ stop_filter.finish()
+ self.assertEqual("".join(output), "answer ")
+ self.assertEqual(stop_filter.matched, "STOP")
+ self.assertEqual(stop_filter.spans, [(0, 7, 0)])
+
+ def test_a_swallowed_marker_and_a_match_in_the_same_feed_call(self):
+ # Both events resolve inside a single feed(), where only the loop's local cursor
+ # has advanced past the swallowed marker. Reading the wrong one shifts the whole
+ # map to 0: "answer" would be reported as raw [0, 6) instead of [8, 14).
+ # "<|user|>" [0,8) ignored - "answer" [8,14) emitted - "<|user|>tail" dropped
+ output = []
+ stop_filter = StopFilter(("<|user|>",), output.append, ignore_leading=True,
+ track_spans=True)
+ stop_filter.feed("<|user|>answer<|user|>tail")
+ stop_filter.finish()
+ self.assertEqual("".join(output), "answer")
+ self.assertEqual(stop_filter.matched, "<|user|>")
+ self.assertEqual(stop_filter.leading_matches_ignored, 1)
+ self.assertEqual(stop_filter.spans, [(8, 14, 0)])
+
+ def test_two_ignored_markers_then_a_real_match_leave_both_holes(self):
+ # Raw is
+ # "<|user|>" "<|user|>" "ok " "STOP" "rest" = [0,8) [8,16) [16,19) [19,23) [23,27)
+ # The map is the single interval [16, 19): everything else was dropped here.
+ output = []
+ stop_filter = StopFilter(("<|user|>", "STOP"), output.append, ignore_leading=True,
+ track_spans=True)
+ for chunk in ("<|user|>", "<|user|>", "ok ", "STOPrest"):
+ stop_filter.feed(chunk)
+ stop_filter.finish()
+ self.assertEqual("".join(output), "ok ")
+ self.assertEqual(stop_filter.leading_matches_ignored, 2)
+ self.assertEqual(stop_filter.matched, "STOP")
+ self.assertEqual(stop_filter.spans, [(16, 19, 0)])
+
+ def test_map_survives_arbitrary_chunking_of_the_same_raw_stream(self):
+ # Fed in three-character chunks, so every marker and the stop sequence straddle a
+ # feed() boundary. Two holes, written out by hand from the string:
+ # [0, 8) the first "<|user|>" ignored (leading)
+ # [8, 10) the two spaces emitted at output 0 -- they flush before the
+ # second marker is visible, and blanks never set useful_content_seen,
+ # so the marker after them is still leading
+ # [10,18) the second "<|user|>" ignored (leading)
+ # [18,29) "alpha beta " emitted at output 2
+ # [29,37) "STOPtail" dropped at the match
+ raw = "<|user|> <|user|>alpha beta STOPtail"
+ output = []
+ stop_filter = StopFilter(("<|user|>", "STOP"), output.append, ignore_leading=True,
+ track_spans=True)
+ for size in range(0, len(raw), 3):
+ stop_filter.feed(raw[size:size + 3])
+ stop_filter.finish()
+ self.assertEqual(stop_filter.spans, [(8, 10, 0), (18, 29, 2)])
+ self.assertEqual("".join(output), " alpha beta ")
+ # ...and the relational form the literals above make non-vacuous: slicing the raw
+ # stream by the map rebuilds exactly what the filter emitted.
+ self.assertEqual("".join(raw[start:end] for start, end, _out in stop_filter.spans),
+ "".join(output))
+
+ def test_spans_are_not_collected_unless_the_caller_asks(self):
+ output = []
+ stop_filter = StopFilter(("STOP",), output.append)
+ stop_filter.feed("plain text")
+ stop_filter.finish()
+ self.assertEqual("".join(output), "plain text")
+ self.assertEqual(stop_filter.spans, [])
+
+
+class StageSpanReportingTest(unittest.TestCase):
+ """The thinking split and the tool-call parse report maps that describe the text they
+ return: slicing the stage's input by its map rebuilds the stage's output exactly."""
+
+ def _assert_map_rebuilds(self, source, produced, span_map):
+ self.assertEqual("".join(source[start:end] for start, end, _out in span_map),
+ produced)
+
+ def test_thinking_split_maps_both_buckets(self):
+ raw = THINK_OPEN + "why" + THINK_CLOSE + "answer"
+ thinking, answer, (thinking_map, answer_map) = split_thinking_reply_spans(raw)
+ self.assertEqual((thinking, answer), ("why", "answer"))
+ self._assert_map_rebuilds(raw, thinking, thinking_map)
+ self._assert_map_rebuilds(raw, answer, answer_map)
+
+ def test_thinking_split_map_is_empty_when_the_bucket_is(self):
+ raw = "plain answer"
+ thinking, answer, (thinking_map, answer_map) = split_thinking_reply_spans(
+ raw, enable_thinking=False)
+ self.assertEqual((thinking, answer), ("", "plain answer"))
+ self.assertEqual(thinking_map, [])
+ self._assert_map_rebuilds(raw, answer, answer_map)
+
+ def test_tool_call_parse_maps_the_content_it_returns(self):
+ tools = [{"function": {"name": "search",
+ "parameters": {"properties": {"q": {"type": "string"}}}}}]
+ raw = ("before <tool_call>search<arg_key>q</arg_key><arg_value>x</arg_value>"
+ "</tool_call> after")
+ content, calls, box_map, content_map = parse_tool_calls_spans(raw, tools)
+ self.assertEqual(len(calls), 1)
+ self.assertEqual(content, "before after")
+ self._assert_map_rebuilds(raw, content, content_map)
+ # The box map stops after the tool-call removal, before the strip: it is what tells
+ # a character consumed as tool-call syntax apart from one consumed as markup.
+ self._assert_map_rebuilds(raw, "before after", box_map)
+
+ def test_tool_call_parse_map_covers_the_thinking_prefix_it_drops(self):
+ raw = "reasoning" + THINK_CLOSE + " visible "
+ content, calls, _box_map, content_map = parse_tool_calls_spans(raw, None)
+ self.assertEqual((content, calls), ("visible", []))
+ self._assert_map_rebuilds(raw, content, content_map)
+
+ def test_shims_return_exactly_what_the_span_forms_do(self):
+ raw = THINK_OPEN + "why" + THINK_CLOSE + " answer "
+ self.assertEqual(split_thinking_reply(raw), split_thinking_reply_spans(raw)[:2])
+ self.assertEqual(parse_tool_calls(raw), parse_tool_calls_spans(raw)[:2])
+ self.assertEqual(parse_arch_tool_calls(raw, None),
+ parse_arch_tool_calls_spans(raw, None)[:2])
+
+
class ProtocolTest(unittest.TestCase):
def test_reads_payload_and_extended_status(self):
stream = io.BytesIO(b"hello" + END + b"STAT 2 3.5 44 1.2 7 1\n")