Skip to content

Commit 9c622e6

Browse files
authored
Python: fix(core): fold streamed text runs in one pass instead of repeated += (microsoft#8953)
* Python: fix(core): fold streamed text runs in one pass instead of repeated += _coalesce_text_content folded chunks with first_new_content += content, and every Content.__add__ rebuilds the text string, re-merges additional_properties, and re-concatenates raw_representation lists, so aggregating n chunks cost O(n^2) (microsoft#8908). Collect each mergeable run and fold it in one pass in _merge_content_run: one join per segment, a single props merge (the earliest chunk still wins per key), one flattened raw-representation list. The fold reproduces the old semantics exactly, including the run head's raw representation being dropped (the old path deep-copied the head, and deepcopy discards raw_representation via _SHALLOW_COPY_FIELDS) and the text_reasoning id / reasoning-text split boundaries. 16000 chunks: 0.302s -> 0.011s on this machine. Signed-off-by: Yufeng He <[email protected]> * Python: fix(core): match the repeated-+= id fallback and detach the run head in the one-pass fold Two exactness gaps against the old fold, both found by fuzzing old vs new: - id for a text_reasoning run fell back to None when no chunk carried a truthy id, but repeated `self.id or other.id` yields the last chunk's value there (so an all-falsy run ending in id="" kept ""). Fall back to run[-1].id. - the old path deep-copied the run head before folding, so the aggregate never aliased the head's nested additional_properties values or annotation dicts. The one-pass merge reused them. Deep-copy the head's contributions the same way. Also harden the equivalence tests: compare raw_representation explicitly (Content.__eq__ skips it, and the oracle's expected side now uses shallow copies so deepcopy does not strip raw up front), cover annotations on head/later chunks, and add a seeded fuzz test folding random streams through the live __add__ so future drift between the add-path and the one-pass fold fails CI. Cross-reference _merge_content_run from _add_text_content/_add_text_reasoning_content. * Python: test(core): narrow the optional props before subscripting in the detach test The four test type checkers all rejected subscripting Content's optional additional_properties/annotations directly. Bind and assert them first. Signed-off-by: Yufeng He <[email protected]> --------- Signed-off-by: Yufeng He <[email protected]>
1 parent 3e6db91 commit 9c622e6

2 files changed

Lines changed: 322 additions & 29 deletions

File tree

‎python/packages/core/agent_framework/_types.py‎

Lines changed: 104 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1738,7 +1738,11 @@ def __add__(self, other: Content) -> Content:
17381738
raise ContentError(f"Addition not supported for content type: {self.type}")
17391739

17401740
def _add_text_content(self, other: Content) -> Content:
1741-
"""Add two TextContent instances."""
1741+
"""Add two TextContent instances.
1742+
1743+
Keep the merge rules here in sync with ``_merge_content_run``, which
1744+
folds a run of chunks in one pass without calling ``__add__``.
1745+
"""
17421746
return Content(
17431747
"text",
17441748
text=self.text + other.text, # type: ignore[attr-defined, operator]
@@ -1748,7 +1752,12 @@ def _add_text_content(self, other: Content) -> Content:
17481752
)
17491753

17501754
def _add_text_reasoning_content(self, other: Content) -> Content:
1751-
"""Add two TextReasoningContent instances."""
1755+
"""Add two TextReasoningContent instances.
1756+
1757+
Keep the mismatch checks and merge rules here in sync with
1758+
``_coalesce_text_content`` / ``_merge_content_run``, which fold a run of
1759+
chunks in one pass without calling ``__add__``.
1760+
"""
17521761
# Ensure we do not silently merge contents with conflicting ids
17531762
if self.id and other.id and self.id != other.id:
17541763
raise AdditionItemMismatch(
@@ -2399,39 +2408,105 @@ def _merge_function_call_content(message: Message, content: Content) -> None:
23992408
message.contents.append(content)
24002409

24012410

2411+
def _merge_content_run(run: list[Content], type_str: Literal["text", "text_reasoning"]) -> Content:
2412+
"""Fold a collected run of same-type contents in one pass.
2413+
2414+
The result matches folding the run with repeated ``+=``: the earliest chunk
2415+
wins per additional-property key, annotations concatenate in order, and raw
2416+
representations flatten into one list (left untouched when a single chunk
2417+
carries the only value). The run head's own raw representation is dropped,
2418+
matching the old path whose initial ``deepcopy`` discards it
2419+
(``_SHALLOW_COPY_FIELDS``). The head's nested values are deep-copied for the
2420+
same reason, so mutating the source head after the fold cannot leak into
2421+
the aggregate.
2422+
"""
2423+
head = run[0]
2424+
merged_props: dict[str, Any] = {}
2425+
for content in reversed(run[1:]):
2426+
merged_props.update(content.additional_properties)
2427+
merged_props.update(deepcopy(head.additional_properties))
2428+
annotation_seqs = [
2429+
deepcopy(c.annotations) if c is head else c.annotations for c in run if c.annotations is not None
2430+
]
2431+
annotations = [a for seq in annotation_seqs for a in seq] if annotation_seqs else None
2432+
non_null_raws = [c.raw_representation for c in run[1:] if c.raw_representation is not None]
2433+
raw_representation: Any
2434+
if not non_null_raws:
2435+
raw_representation = None
2436+
elif len(non_null_raws) == 1:
2437+
raw_representation = non_null_raws[0]
2438+
else:
2439+
raw_representation = []
2440+
for raw in non_null_raws:
2441+
raw_representation.extend(raw if isinstance(raw, list) else [raw])
2442+
if type_str == "text":
2443+
return Content(
2444+
"text",
2445+
text="".join(c.text or "" for c in run),
2446+
annotations=annotations,
2447+
additional_properties=merged_props,
2448+
raw_representation=raw_representation,
2449+
)
2450+
return Content(
2451+
"text_reasoning",
2452+
id=next((c.id for c in run if c.id), run[-1].id),
2453+
text=None if all(c.text is None for c in run) else "".join(c.text or "" for c in run),
2454+
protected_data=next((c.protected_data for c in reversed(run) if c.protected_data is not None), None),
2455+
annotations=annotations,
2456+
additional_properties=merged_props,
2457+
raw_representation=raw_representation,
2458+
)
2459+
2460+
24022461
def _coalesce_text_content(contents: list[Content], type_str: Literal["text", "text_reasoning"]) -> None:
2403-
"""Take any subsequence Text or TextReasoningContent items and coalesce them into a single item."""
2462+
"""Take any subsequence Text or TextReasoningContent items and coalesce them into a single item.
2463+
2464+
Mergeable runs are collected and folded in a single pass, so aggregating n
2465+
chunks costs O(n) instead of the O(n^2) of repeated ``+=``.
2466+
"""
24042467
if not contents:
24052468
return
24062469
coalesced_contents: list[Content] = []
2407-
first_new_content: Any | None = None
2470+
run: list[Content] = []
2471+
run_id: str | None = None
2472+
run_has_text = False
2473+
run_has_reasoning_text = False
2474+
2475+
def flush() -> None:
2476+
nonlocal run_id, run_has_text, run_has_reasoning_text
2477+
if run:
2478+
coalesced_contents.append(deepcopy(run[0]) if len(run) == 1 else _merge_content_run(run, type_str))
2479+
run.clear()
2480+
run_id = None
2481+
run_has_text = run_has_reasoning_text = False
2482+
24082483
for content in contents:
2409-
if content.type == type_str:
2410-
if first_new_content is None:
2411-
first_new_content = deepcopy(content)
2412-
elif type_str == "text" and first_new_content.additional_properties.get(
2413-
_MODEL_OUTPUT_KIND_KEY
2414-
) != content.additional_properties.get(_MODEL_OUTPUT_KIND_KEY):
2415-
coalesced_contents.append(first_new_content)
2416-
first_new_content = deepcopy(content)
2417-
else:
2418-
try:
2419-
first_new_content += content
2420-
except AdditionItemMismatch:
2421-
# Different IDs means a new logical segment; flush the current one
2422-
coalesced_contents.append(first_new_content)
2423-
first_new_content = deepcopy(content)
2424-
else:
2425-
# skip this content, it is not of the right type
2426-
# so write the existing one to the list and start a new one,
2427-
# once the right type is found again
2428-
if first_new_content:
2429-
coalesced_contents.append(first_new_content)
2430-
first_new_content = None
2431-
# but keep the other content in the new list
2484+
if content.type != type_str:
2485+
flush()
24322486
coalesced_contents.append(content)
2433-
if first_new_content:
2434-
coalesced_contents.append(first_new_content)
2487+
continue
2488+
if run:
2489+
if type_str == "text":
2490+
# A folded run keeps the first chunk's value for this key, so the
2491+
# run head alone decides whether the next chunk joins or splits.
2492+
if run[0].additional_properties.get(_MODEL_OUTPUT_KIND_KEY) != content.additional_properties.get(
2493+
_MODEL_OUTPUT_KIND_KEY
2494+
):
2495+
flush()
2496+
else:
2497+
other_id: str | None = getattr(content, "id", None)
2498+
if (run_id and other_id and run_id != other_id) or (
2499+
run_has_text
2500+
and getattr(content, "text", None)
2501+
and (run_has_reasoning_text != ("reasoning_text" in content.additional_properties))
2502+
):
2503+
flush()
2504+
run.append(content)
2505+
if type_str == "text_reasoning":
2506+
run_id = run_id or getattr(content, "id", None)
2507+
run_has_text = run_has_text or bool(getattr(content, "text", None))
2508+
run_has_reasoning_text = run_has_reasoning_text or "reasoning_text" in content.additional_properties
2509+
flush()
24352510
contents.clear()
24362511
contents.extend(coalesced_contents)
24372512

‎python/packages/core/tests/core/test_types.py‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
import json
77
import warnings
88
from collections.abc import AsyncIterable, AsyncIterator, Awaitable, Callable, Sequence
9+
from copy import copy, deepcopy
910
from dataclasses import dataclass
1011
from datetime import datetime, timezone
1112
from functools import partial
@@ -41,6 +42,7 @@
4142
GROUP_TOKEN_COUNT_KEY,
4243
)
4344
from agent_framework._types import (
45+
_MODEL_OUTPUT_KIND_KEY,
4446
_append_instructions,
4547
_get_data_bytes,
4648
_get_data_bytes_as_str,
@@ -2580,6 +2582,222 @@ def test_coalesce_text_reasoning_with_different_ids():
25802582
assert contents[1].text == "Thinking B1 B2"
25812583

25822584

2585+
def _reference_coalesce(contents: list[Content], type_str: Literal["text", "text_reasoning"]) -> None:
2586+
"""The pre-fix fold, kept as the equivalence oracle: deepcopy the run head, then += the rest."""
2587+
if not contents:
2588+
return
2589+
coalesced: list[Content] = []
2590+
acc: Content | None = None
2591+
for content in contents:
2592+
if content.type == type_str:
2593+
if acc is None:
2594+
acc = deepcopy(content)
2595+
elif type_str == "text" and acc.additional_properties.get(
2596+
_MODEL_OUTPUT_KIND_KEY
2597+
) != content.additional_properties.get(_MODEL_OUTPUT_KIND_KEY):
2598+
coalesced.append(acc)
2599+
acc = deepcopy(content)
2600+
else:
2601+
try:
2602+
acc += content
2603+
except AdditionItemMismatch:
2604+
coalesced.append(acc)
2605+
acc = deepcopy(content)
2606+
else:
2607+
if acc:
2608+
coalesced.append(acc)
2609+
acc = None
2610+
coalesced.append(content)
2611+
if acc:
2612+
coalesced.append(acc)
2613+
contents.clear()
2614+
contents.extend(coalesced)
2615+
2616+
2617+
@pytest.mark.parametrize("type_str", ["text", "text_reasoning"])
2618+
def test_coalesce_matches_repeated_add(type_str: Literal["text", "text_reasoning"]) -> None:
2619+
"""The one-pass fold must reproduce the repeated-+= result on a mixed stream."""
2620+
from agent_framework._types import _coalesce_text_content
2621+
2622+
def make(i: int, **kwargs: Any) -> Content:
2623+
if type_str == "text":
2624+
return Content.from_text(f"chunk{i} ", **kwargs)
2625+
return Content.from_text_reasoning(text=f"chunk{i} ", **kwargs)
2626+
2627+
streams = [
2628+
# plain run
2629+
[make(i) for i in range(5)],
2630+
# run with props, annotations and raw representations of mixed shapes
2631+
[
2632+
make(0, additional_properties={"a": 1}, raw_representation={"n": 0}),
2633+
make(1, additional_properties={"a": 2, "b": 1}, raw_representation=[{"n": 1}]),
2634+
make(2),
2635+
make(3, raw_representation={"n": 3}),
2636+
],
2637+
# annotations on the head, on a later chunk, and on both
2638+
[
2639+
make(0, annotations=[{"type": "citation", "url": "https://a"}]),
2640+
make(1),
2641+
make(2, annotations=[{"type": "citation", "url": "https://b"}]),
2642+
],
2643+
[make(0), make(1, annotations=[{"type": "citation", "url": "https://b"}]), make(2)],
2644+
# split by an unrelated content type, then resume
2645+
[make(0), Content.from_data(b"\x00", media_type="application/octet-stream"), make(1), make(2)],
2646+
# single chunk stays a plain copy
2647+
[make(0, raw_representation={"n": 0})],
2648+
]
2649+
if type_str == "text":
2650+
marker = {_MODEL_OUTPUT_KIND_KEY: "refusal"}
2651+
streams.append([make(0), make(1, additional_properties=marker), make(2, additional_properties=marker), make(3)])
2652+
else:
2653+
streams.append([make(0, id="rs_a"), make(1, id="rs_a"), make(2, id="rs_b"), make(3)])
2654+
streams.append([
2655+
make(0, additional_properties={"reasoning_text": True}),
2656+
make(1),
2657+
make(2, additional_properties={"reasoning_text": True}),
2658+
])
2659+
2660+
for stream in streams:
2661+
# Shallow copies: deepcopy would strip raw_representation up front and make
2662+
# the explicit raw comparison below vacuous.
2663+
expected = [copy(c) for c in stream]
2664+
_reference_coalesce(expected, type_str)
2665+
actual = list(stream)
2666+
_coalesce_text_content(actual, type_str)
2667+
assert actual == expected, type_str
2668+
# Content.__eq__ excludes raw_representation, so compare it explicitly.
2669+
assert [c.raw_representation for c in actual] == [c.raw_representation for c in expected], type_str
2670+
2671+
2672+
def test_coalesce_fold_does_not_readd_chunks() -> None:
2673+
"""Aggregating n chunks must not invoke Content.__add__ per chunk (the old O(n^2) path)."""
2674+
from agent_framework._types import _coalesce_text_content
2675+
2676+
calls = 0
2677+
original_add = Content.__add__
2678+
2679+
def counting_add(self: Content, other: Content) -> Content:
2680+
nonlocal calls
2681+
calls += 1
2682+
return original_add(self, other)
2683+
2684+
contents = [Content.from_text(f"c{i} ", raw_representation={"i": i}) for i in range(2000)]
2685+
try:
2686+
Content.__add__ = counting_add # type: ignore[method-assign]
2687+
_coalesce_text_content(contents, "text")
2688+
finally:
2689+
Content.__add__ = original_add # type: ignore[method-assign]
2690+
2691+
assert calls == 0
2692+
assert len(contents) == 1
2693+
assert contents[0].text == "".join(f"c{i} " for i in range(2000))
2694+
# The run head's raw representation is dropped by the fold's deepcopy semantics;
2695+
# the remaining 1999 entries flatten in order.
2696+
assert contents[0].raw_representation == [{"i": i} for i in range(1, 2000)]
2697+
2698+
2699+
def test_coalesce_text_reasoning_one_pass_semantics() -> None:
2700+
"""text_reasoning specifics: id from the first tagged chunk, protected_data from the last non-null."""
2701+
from agent_framework._types import _coalesce_text_content
2702+
2703+
contents = [
2704+
Content.from_text_reasoning(id="rs_a", text="t1", protected_data="sig1"),
2705+
Content.from_text_reasoning(text="t2"),
2706+
Content.from_text_reasoning(text=None, protected_data="sig2"),
2707+
]
2708+
_coalesce_text_content(contents, "text_reasoning")
2709+
assert len(contents) == 1
2710+
assert contents[0].id == "rs_a"
2711+
assert contents[0].text == "t1t2"
2712+
assert contents[0].protected_data == "sig2"
2713+
2714+
# a fully text-less run keeps text=None rather than ""
2715+
none_run = [Content.from_text_reasoning(text=None), Content.from_text_reasoning(text=None)]
2716+
_coalesce_text_content(none_run, "text_reasoning")
2717+
assert len(none_run) == 1
2718+
assert none_run[0].text is None
2719+
2720+
2721+
def test_coalesce_text_reasoning_empty_id_matches_repeated_add() -> None:
2722+
"""An empty-string id survives the fold exactly like repeated += (``None or ""`` yields ``""``)."""
2723+
from agent_framework._types import _coalesce_text_content
2724+
2725+
contents = [Content.from_text_reasoning(text="a"), Content.from_text_reasoning(id="", text="b")]
2726+
_coalesce_text_content(contents, "text_reasoning")
2727+
assert len(contents) == 1
2728+
assert contents[0].id == ""
2729+
2730+
2731+
def test_coalesce_detaches_run_head_nested_values() -> None:
2732+
"""Mutating the source head's nested values after the fold must not leak into the aggregate."""
2733+
from agent_framework._types import _coalesce_text_content
2734+
2735+
head = Content.from_text(
2736+
"h ",
2737+
additional_properties={"k": {"nested": 1}},
2738+
annotations=[{"type": "citation", "url": "https://a"}],
2739+
)
2740+
contents = [head, Content.from_text("t")]
2741+
_coalesce_text_content(contents, "text")
2742+
props = head.additional_properties
2743+
annotations = head.annotations
2744+
assert props is not None and annotations is not None
2745+
props["k"]["nested"] = 99
2746+
annotations[0]["url"] = "https://mutated"
2747+
folded_props = contents[0].additional_properties
2748+
folded_annotations = contents[0].annotations
2749+
assert folded_props is not None and folded_annotations is not None
2750+
assert folded_props["k"]["nested"] == 1
2751+
assert folded_annotations[0]["url"] == "https://a"
2752+
2753+
2754+
@pytest.mark.parametrize("type_str", ["text", "text_reasoning"])
2755+
def test_coalesce_matches_repeated_add_fuzz(type_str: Literal["text", "text_reasoning"]) -> None:
2756+
"""Seeded random streams: the one-pass fold must match repeated += exactly.
2757+
2758+
The oracle folds through the live ``__add__``, so any future drift between
2759+
the add-path and the one-pass fold fails here.
2760+
"""
2761+
import random
2762+
2763+
from agent_framework._types import _coalesce_text_content
2764+
2765+
rng = random.Random(20261002)
2766+
2767+
def rand_chunk() -> Content:
2768+
kwargs: dict[str, Any] = {}
2769+
if rng.random() < 0.5:
2770+
props: dict[str, Any] = {rng.choice(["a", "b"]): rng.randint(0, 3)}
2771+
if type_str == "text" and rng.random() < 0.2:
2772+
props[_MODEL_OUTPUT_KIND_KEY] = rng.choice(["refusal", "regular"])
2773+
if type_str == "text_reasoning" and rng.random() < 0.3:
2774+
props["reasoning_text"] = True
2775+
kwargs["additional_properties"] = props
2776+
if rng.random() < 0.3:
2777+
annotation: Annotation = {"type": "citation", "url": f"https://x/{rng.randint(0, 9)}"}
2778+
kwargs["annotations"] = [annotation]
2779+
if rng.random() < 0.4:
2780+
kwargs["raw_representation"] = (
2781+
{"n": rng.randint(0, 5)} if rng.random() < 0.5 else [{"n": rng.randint(0, 5)}]
2782+
)
2783+
if type_str == "text":
2784+
return Content.from_text(rng.choice(["", "x", "y "]), **kwargs)
2785+
return Content.from_text_reasoning(
2786+
id=rng.choice([None, "", "rs_a", "rs_b"]), text=rng.choice([None, "", "t "]), **kwargs
2787+
)
2788+
2789+
for _ in range(300):
2790+
stream = [rand_chunk() for _ in range(rng.randint(0, 8))]
2791+
if stream and rng.random() < 0.3:
2792+
stream.insert(rng.randrange(len(stream)), Content.from_data(b"\x00", media_type="application/octet-stream"))
2793+
expected = [copy(c) for c in stream]
2794+
_reference_coalesce(expected, type_str)
2795+
actual = list(stream)
2796+
_coalesce_text_content(actual, type_str)
2797+
assert actual == expected
2798+
assert [c.raw_representation for c in actual] == [c.raw_representation for c in expected]
2799+
2800+
25832801
def test_agent_response_from_updates_preserves_refusal_marker() -> None:
25842802
marker = {"model_output_kind": "refusal"}
25852803
response = AgentResponse.from_updates([

0 commit comments

Comments
 (0)