DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""Build budgeted conversation history for unified chat sessions."""
from __future__ import annotations
from dataclasses import dataclass, field
import json
import logging
import os
import re
from typing import Any, Awaitable, Callable
from deeptutor.agents.base_agent import BaseAgent
from deeptutor.core.stream import StreamEvent, StreamEventType
from deeptutor.core.trace import build_trace_metadata, merge_trace_metadata, new_call_id
from deeptutor.services.llm.config import LLMConfig
from deeptutor.services.llm.context_window import (
coerce_positive_int,
resolve_effective_context_window,
)
from deeptutor.services.llm.image_replay import deduplicate_user_images
from deeptutor.services.llm.types import StreamOutcome
from deeptutor.services.prompt.language import language_label
from .ask_user_trace import (
extract_ask_user_clarification_blocks,
extract_ask_user_clarifications,
)
from .model_history import (
SUMMARY_SNAPSHOT_NAME,
history_groups,
model_turn,
replay_history,
summary_snapshot,
)
from .protocol import SessionStoreProtocol
from .provider_response_state import normalize_provider_response_state
logger = logging.getLogger(__name__)
#: When the summarizer's output lands within this fraction of its hard token
#: cap, assume the provider cut it mid-sentence and trim the partial tail.
TRUNCATION_GUARD_RATIO = 0.95
# Ratio-only budgets become impractical for models with very large context
# windows: a 1M-token window would otherwise reserve hundreds of thousands of
# tokens for chat history and ask the summarizer for a six-figure response.
# Keep the rolling-summary strategy, but bound its history plan, summary
# output, and raw-rebuild eligibility threshold. The summary ceiling is also
# constrained by the active generation limit when that setting is lower.
MAX_HISTORY_PLAN_TOKENS = 131_072
MAX_SUMMARY_OUTPUT_TOKENS = 16_384
MAX_RAW_REBUILD_TOKENS = 131_072
logger = logging.getLogger(__name__)
# Planning allowance per image, not provider-reported usage. Counting encoded
# image bytes as text can exhaust the entire history budget on one screenshot.
# Reserve nonzero headroom for vision while keeping it independent of PNG/JPEG
# compression and URL length. Apply request projection before counting so only
# images retained in the request consume this allowance; references remain text.
IMAGE_CONTEXT_TOKEN_ESTIMATE = 4096
# The summarizer's scratchpad has to be removed defensively: a custom
# OpenAI-compatible route can emit the model's reasoning inline instead of on a
# separate reasoning channel, and the observed output *began* with the drafting
# monologue under an unclosed tag. ``clean_thinking_tags`` removes an unclosed
# block through end of text, which here would have discarded the entire
# summary, so the tag is only trusted when it is closed.
_CLOSED_THINK_RE = re.compile(
r"<\s*think(?:ing)?\b[^>]*>.*?<\s*/\s*think(?:ing)?\s*>", re.DOTALL | re.IGNORECASE
)
_OPEN_THINK_RE = re.compile(r"^<\s*think(?:ing)?\b[^>]*>", re.IGNORECASE | re.DOTALL)
_SUMMARY_SECTION_RE = re.compile(r"(?m)^[ \t]{0,3}#{1,6}[ \t]")
_MIN_SALVAGED_CHARS = 200
def sanitize_summary(text: str) -> str:
"""Drop a leaked reasoning scratchpad without ever losing the summary.
A summary is replayed on every later turn until the next compaction, so
scratchpad that leaks into it is paid for on every request — and, because
the scratchpad is written first, it also eats the summarizer's generation
budget and truncates the real content.
"""
raw = (text or "").strip()
if not raw:
return ""
cleaned = _CLOSED_THINK_RE.sub("", raw).strip()
match = _OPEN_THINK_RE.match(cleaned)
if match is None:
return cleaned
body = cleaned[match.end() :]
# The tag was never closed: cut at the first heading the summarizer was
# told to emit, and accept the cut only when a real body survives it.
section = _SUMMARY_SECTION_RE.search(body)
if section is not None and len(body) - section.start() >= _MIN_SALVAGED_CHARS:
return body[section.start() :].strip()
# Unstructured output: drop the marker itself rather than the content.
return _OPEN_THINK_RE.sub("", cleaned).replace("</think>", "").strip() or raw
def count_tokens(text: str) -> int:
"""Estimate token count with tiktoken when available."""
if not text:
return 0
try:
import tiktoken
encoding = tiktoken.get_encoding("cl100k_base")
return len(encoding.encode(text))
except Exception:
return max(1, len(text) // 4)
def _count_model_context_tokens(value: Any) -> int:
"""Measure a temporary accounting view; never alter the replay payload.
Keep all text, tool arguments/results and provider replay state in the
existing serialized-text estimate. Only recognized multimodal image blocks
use a separate allowance; their encoded bytes/URLs are not language tokens.
This is a context-planning heuristic, not an exact vision billing counter.
"""
image_count = 0
def accounting_view(item: Any) -> Any:
nonlocal image_count
if isinstance(item, dict):
kind = item.get("type")
is_image = (
(kind == "image_url" and "image_url" in item)
or (kind == "input_image" and ("image_url" in item or "file_id" in item))
or (kind == "image" and "source" in item)
)
if is_image:
image_count += 1
return {"type": "image"}
return {key: accounting_view(child) for key, child in item.items()}
if isinstance(item, list):
return [accounting_view(child) for child in item]
return item
serialized = json.dumps(accounting_view(value), ensure_ascii=False)
return count_tokens(serialized) + image_count * IMAGE_CONTEXT_TOKEN_ESTIMATE
def _count_projected_model_tokens(replay: list[dict[str, Any]]) -> int:
projected_tokens = _count_model_context_tokens(deduplicate_user_images(replay))
if logger.isEnabledFor(logging.DEBUG):
logger.debug(
"History budget: raw_replay_tokens=%d projected_replay_tokens=%d",
_count_model_context_tokens(replay),
projected_tokens,
)
return projected_tokens
def trim_incomplete_tail(text: str) -> str:
"""Drop the trailing partial line from output that hit a hard token cap.
A summary cut mid-sentence would otherwise be persisted as-is; losing the
last line is cheaper than carrying a corrupted entry forward.
"""
lines = text.rstrip().split("\n")
if len(lines) > 1:
return "\n".join(lines[:-1]).rstrip()
return text.rstrip()
def expand_message_context(message: dict[str, Any]) -> list[dict[str, Any]]:
"""Expand one stored row into its true assistant/user chronology."""
role = str(message.get("role", "user"))
content = str(message.get("content", "") or "")
blocks = extract_ask_user_clarification_blocks(message)
if role != "assistant" or not blocks:
return [{"role": role, "content": content}] if content.strip() else []
expanded: list[dict[str, str]] = []
cursor = 0
for raw_offset, clarification in blocks:
offset = min(len(content), max(cursor, raw_offset))
prefix = content[cursor:offset]
if prefix.strip():
expanded.append({"role": "assistant", "content": prefix})
expanded.append({"role": "user", "content": clarification})
cursor = offset
suffix = content[cursor:]
if suffix.strip():
expanded.append({"role": "assistant", "content": suffix})
return expanded
def format_messages_as_transcript(messages: list[dict[str, Any]]) -> str:
lines: list[str] = []
role_map = {
"user": "User",
"assistant": "Assistant",
"system": "System",
}
for item in messages:
for expanded in expand_message_context(item):
content = expanded["content"].strip()
role = role_map.get(expanded["role"], "User")
lines.append(f"{role}: {content}")
return "\n\n".join(lines)
def build_history_text(history: list[dict[str, Any]]) -> str:
lines: list[str] = []
for item in history:
role = str(item.get("role", "user"))
content = str(item.get("content", "") or "").strip()
if not content:
continue
if role == "system":
lines.append(f"Conversation summary:\n{content}")
elif role == "assistant":
lines.append(f"Assistant: {content}")
else:
lines.append(f"User: {content}")
return "\n\n".join(lines)
def _provider_response_state_tokens(message: dict[str, Any]) -> int:
metadata = message.get("metadata")
state = normalize_provider_response_state(
metadata.get("provider_response_state") if isinstance(metadata, dict) else None
)
if state is None:
return 0
try:
serialized = json.dumps(state, ensure_ascii=False, separators=(",", ":"))
except (TypeError, ValueError):
serialized = str(state)
return count_tokens(serialized)
@dataclass
class ContextBuildResult:
conversation_history: list[dict[str, Any]]
conversation_summary: str
context_text: str
events: list[StreamEvent]
token_count: int
budget: int
model_history: list[dict[str, Any]] | None = None
previous_model_turn: dict[str, Any] | None = None
history_sources: dict[str, str] = field(default_factory=dict)
class _ContextSummaryAgent(BaseAgent):
"""Small helper agent for compressing older conversation turns."""
def __init__(self, language: str = "en") -> None:
super().__init__(
module_name="chat",
agent_name="context_summary_agent",
language=language,
)
async def process(self, *_args, **_kwargs) -> dict[str, Any]:
raise NotImplementedError
class ContextBuilder:
"""Construct history against a bounded plan plus optional summary trace.
The budget is a planning target, not destructive truncation: the newest
non-empty message is retained even when that single message exceeds it.
"""
def __init__(
self,
store: SessionStoreProtocol,
history_budget_ratio: float = 0.35,
summary_target_ratio: float = 0.40,
) -> None:
self.store = store
self.history_budget_ratio = history_budget_ratio
self.summary_target_ratio = summary_target_ratio
def _effective_context_window(self, llm_config: LLMConfig) -> int:
return resolve_effective_context_window(
context_window=getattr(llm_config, "context_window", None),
model=str(getattr(llm_config, "model", "") or ""),
max_tokens=getattr(llm_config, "max_tokens", None),
)
def _history_budget(self, llm_config: LLMConfig) -> int:
effective_context_window = self._effective_context_window(llm_config)
ratio_budget = max(256, int(effective_context_window * self.history_budget_ratio))
return min(ratio_budget, MAX_HISTORY_PLAN_TOKENS)
def _summary_budget(self, budget: int, llm_config: LLMConfig | None = None) -> int:
ratio_budget = max(96, int(budget * self.summary_target_ratio))
output_cap = MAX_SUMMARY_OUTPUT_TOKENS
if llm_config is not None:
generation_limit = coerce_positive_int(getattr(llm_config, "max_tokens", None))
if generation_limit is not None:
output_cap = min(output_cap, generation_limit)
return min(ratio_budget, output_cap)
def _recent_budget(self, budget: int) -> int:
# Keep the original ratio-based split independent of the summarizer's
# output cap. Otherwise lowering that cap expands the verbatim tail and
# leaves almost no headroom before the next compaction.
return max(128, int(budget * (1 - self.summary_target_ratio)))
def _rebuild_source_budget(self, llm_config: LLMConfig) -> int:
# A raw prefix is eligible for drift-free rebuild up to this threshold;
# beyond it we degrade to fold-in (existing summary + new turns).
ratio_budget = max(1024, self._effective_context_window(llm_config) // 2)
return min(ratio_budget, MAX_RAW_REBUILD_TOKENS)
def _build_history(self, summary: str, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
history: list[dict[str, Any]] = []
cleaned_summary = summary.strip()
if cleaned_summary:
history.append({"role": "system", "content": cleaned_summary})
for item in messages:
expanded_start = len(history)
for expanded in expand_message_context(item):
if expanded["role"] in {"user", "assistant"}:
history.append(expanded)
if item.get("role") != "assistant":
continue
metadata = item.get("metadata")
provider_state = normalize_provider_response_state(
metadata.get("provider_response_state") if isinstance(metadata, dict) else None
)
if provider_state is None:
continue
for expanded in reversed(history[expanded_start:]):
if expanded.get("role") == "assistant" and expanded.get("content"):
expanded["_provider_response_state"] = provider_state
break
return history
async def _append_event(
self,
events: list[StreamEvent],
event: StreamEvent,
on_event: Callable[[StreamEvent], Awaitable[None]] | None = None,
) -> None:
events.append(event)
if on_event is not None:
await on_event(event)
def _select_recent_messages(
self,
messages: list[dict[str, Any]],
recent_budget: int,
route: dict[str, str] | None = None,
) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
groups = history_groups(messages)
if any(model_turn(row) is not None for row in messages):
# Rebuild each group once, then find the longest fitting suffix.
# Images are shared across turns: adding per-group costs overcounts
# repeats, while replaying every growing tail is quadratic work.
replay_groups = [replay_history(group, route=route) for group in groups]
start, end = 0, len(groups) - 1
while start < end:
middle = (start + end) // 2
candidate = [message for group in replay_groups[middle:] for message in group]
if _count_projected_model_tokens(candidate) <= recent_budget:
end = middle
else:
start = middle + 1
# Always retain the newest whole turn, even if it alone overflows.
cutoff = sum(len(group) for group in groups[:start])
return messages[:cutoff], messages[cutoff:]
selected: list[dict[str, Any]] = []
total = 0
for group in reversed(groups):
tokens = 0
for item in group:
content = str(item.get("content", "") or "")
clarification = extract_ask_user_clarifications(item)
tokens += count_tokens(f"{content}\n{clarification}" if clarification else content)
tokens += _provider_response_state_tokens(item)
if selected and total + tokens > recent_budget:
break
selected[0:0] = group
total += tokens
cutoff = len(messages) - len(selected)
return messages[:cutoff], selected
def _model_tokens(
self,
messages: list[dict[str, Any]],
summary: str = "",
route: dict[str, str] | None = None,
) -> int:
if any(model_turn(row) is not None for row in messages):
replayed = replay_history(messages, route=route)
tokens = _count_projected_model_tokens(replayed)
# The answer loop appends the summary as a trailing snapshot, but
# only when it differs from the revision already replayed with the
# history. Count what the request will actually carry.
pending = summary_snapshot(summary)
if pending is not None and not any(
item.get("_context_snapshot") == SUMMARY_SNAPSHOT_NAME
and item.get("content") == pending["content"]
for item in replayed
):
tokens += _count_model_context_tokens(pending)
return tokens
return count_tokens(build_history_text(self._build_history(summary, messages))) + sum(
_provider_response_state_tokens(row) for row in messages
)
async def _summarize(
self,
*,
session_id: str,
language: str,
source_text: str,
summary_budget: int,
generation_budget: int | None = None,
on_event: Callable[[StreamEvent], Awaitable[None]] | None = None,
replay_request: dict[str, Any] | None = None,
) -> tuple[str, list[StreamEvent]]:
events: list[StreamEvent] = []
if not source_text.strip():
return "", events
agent = _ContextSummaryAgent(language=language)
trace_meta = build_trace_metadata(
call_id=new_call_id("context-summary"),
phase="summarize_context",
label="Summarize context",
call_kind="llm_summarization",
trace_id=session_id,
)
async def _trace_bridge(update: dict[str, Any]) -> None:
if str(update.get("event", "")) != "llm_call":
return
state = str(update.get("state", "running"))
metadata = {
key: value
for key, value in update.items()
if key not in {"event", "state", "response", "chunk"}
}
if state == "running":
await self._append_event(
events,
StreamEvent(
type=StreamEventType.PROGRESS,
source="context_builder",
stage="summarize_context",
content="Compressing conversation history...",
metadata=merge_trace_metadata(
metadata,
{"trace_kind": "call_status", "call_state": "running"},
),
),
on_event,
)
elif state == "complete":
response = str(update.get("response", "") or "")
if response:
await self._append_event(
events,
StreamEvent(
type=StreamEventType.CONTENT,
source="context_builder",
stage="summarize_context",
content=response,
metadata=merge_trace_metadata(
metadata,
{"trace_kind": "llm_output"},
),
),
on_event,
)
await self._append_event(
events,
StreamEvent(
type=StreamEventType.PROGRESS,
source="context_builder",
stage="summarize_context",
content="",
metadata=merge_trace_metadata(
metadata,
{"trace_kind": "call_status", "call_state": "complete"},
),
),
on_event,
)
elif state == "error":
await self._append_event(
events,
StreamEvent(
type=StreamEventType.ERROR,
source="context_builder",
stage="summarize_context",
content=str(update.get("response", "") or "Context summarization failed."),
metadata=merge_trace_metadata(metadata, {"call_state": "error"}),
),
on_event,
)
agent.set_trace_callback(_trace_bridge)
await self._append_event(
events,
StreamEvent(
type=StreamEventType.STAGE_START,
source="context_builder",
stage="summarize_context",
metadata=trace_meta,
),
on_event,
)
# The instruction targets ~80% of the hard cap so the model's own
# length control — not the max_tokens cut — is the binding limit.
target_tokens = max(1, int(summary_budget * 0.8))
# The summary is replayed as a system row on every later turn, so the
# language it is written in keeps steering the answer long after the
# turns it condensed have scrolled out. Unstated, a summary of a
# foreign-language session comes back in the default language and the
# reply follows it — #1511's drift "after a few rounds".
system_prompt = self._summary_instruction(language)
user_prompt = (
f"Update the summary using the material below. "
f"Keep the total under {target_tokens} tokens.\n\n{source_text}"
)
if language.startswith("zh"):
user_prompt = (
f"请基于下面的材料更新摘要,总长度不超过 {target_tokens} tokens。\n\n{source_text}"
)
try:
_chunks: list[str] = []
outcome = StreamOutcome()
replay_kwargs: dict[str, Any] = {}
if replay_request is not None:
# Reuse the conversation's warm prefix; only the instruction
# is new. Tools are present for cache identity, never executed.
instruction = (
f"{system_prompt}\n\nSummarize the conversation above in at most "
f"{target_tokens} tokens. Output only the summary; do not call tools."
)
replay_kwargs = {
"messages": deduplicate_user_images(
[
*replay_request["messages"],
{"role": "user", "content": instruction},
]
),
"tools": replay_request.get("tools"),
}
async for _c in agent.stream_llm(
user_prompt=user_prompt,
system_prompt=system_prompt,
max_tokens=generation_budget or summary_budget,
stage="summarize_context",
trace_meta=trace_meta,
outcome=outcome,
**replay_kwargs,
):
_chunks.append(_c)
summary = sanitize_summary("".join(_chunks))
return self._finalize_summary(summary, summary_budget, outcome), events
finally:
await self._append_event(
events,
StreamEvent(
type=StreamEventType.STAGE_END,
source="context_builder",
stage="summarize_context",
metadata=trace_meta,
),
on_event,
)
def _finalize_summary(self, summary: str, summary_budget: int, outcome: StreamOutcome) -> str:
"""Legacy prose summaries can trim a partial final sentence."""
if count_tokens(summary) >= int(summary_budget * TRUNCATION_GUARD_RATIO):
return trim_incomplete_tail(summary)
return summary
def _summary_instruction(self, language: str) -> str:
"""The summary task's policy, independently of a tutor's large prompt."""
summary_language = language_label(language)
system_prompt = (
"You maintain a running summary of a conversation so future turns can "
"continue seamlessly. Rewrite the summary from the material provided, "
"organized under these headings (omit any heading with no content):\n"
"- Goals: what the user wants to accomplish, and why if stated\n"
"- Key facts & context: stable facts, definitions, data points, names, "
"references (files, links, IDs)\n"
"- Decisions & preferences: choices made, options rejected, style or "
"format preferences, capability/mode switches\n"
"- Progress: what has been produced or completed so far\n"
"- Open items: unanswered questions, pending tasks, known blockers\n"
"Carry forward still-relevant entries from the existing summary unchanged "
"unless new information contradicts them; drop only what is obsolete. "
"Prefer concrete details (numbers, identifiers, exact terms) over "
"abstract restatement. Never invent information. "
"Output the summary body only: no preamble, no drafting notes, no "
"step-by-step reasoning, and no <think> blocks — start directly at "
"the first heading. "
f"Write the summary itself in {summary_language}."
)
if language.startswith("zh"):
system_prompt = (
"你负责维护一份对话的滚动摘要,供后续轮次无缝衔接。请基于给定材料重写摘要,"
"按以下小节组织(无内容的小节直接省略):\n"
"- 目标:用户想完成什么,以及(如有说明)原因\n"
"- 关键事实与上下文:稳定的事实、定义、数据、名称、引用(文件、链接、ID)\n"
"- 决定与偏好:已做的选择、被否决的方案、风格/格式偏好、能力或模式切换\n"
"- 进展:目前已经产出或完成的内容\n"
"- 待办事项:未回答的问题、未完成的任务、已知阻塞\n"
"已有摘要中仍然有效的条目应原样保留,仅在新信息与之矛盾时修改,只删除确已过时"
"的内容。优先保留具体细节(数字、标识符、确切措辞),不要抽象转述,绝不虚构。"
"只输出摘要正文:不要输出任何思考过程或 <think> 标记,不要写草稿、不要写"
"「Let me…」「Draft:」之类的推演,直接从第一个小节标题开始。"
f"摘要正文本身请使用{summary_language}撰写。"
)
return system_prompt
async def build(
self,
*,
session_id: str,
llm_config: LLMConfig,
language: str = "en",
on_event: Callable[[StreamEvent], Awaitable[None]] | None = None,
leaf_message_id: int | None = None,
) -> ContextBuildResult:
session = await self.store.get_session(session_id)
# When ``leaf_message_id`` is given (edit-branch turn), only the
# ancestor path of that message is included in context — sibling
# branches at any depth are excluded.
messages = await self.store.get_messages_for_context(
session_id, leaf_message_id=leaf_message_id
)
if session is None:
return ContextBuildResult([], "", "", [], 0, self._history_budget(llm_config))
budget = self._history_budget(llm_config)
summary_budget = self._summary_budget(budget, llm_config)
recent_budget = self._recent_budget(budget)
stored_summary = str(session.get("compressed_summary", "") or "").strip()
summary_up_to_msg_id = session.get("summary_up_to_msg_id", 0) or 0
# Branch guard: the watermark must sit on this turn's ancestor chain.
# After an edit-branch switch it may point into a sibling branch — the
# stored summary would then carry content this branch never saw.
# Discard both and rebuild from this branch's own messages.
summary_position = next(
(
index
for index, item in enumerate(messages)
if summary_up_to_msg_id and str(item.get("id")) == str(summary_up_to_msg_id)
),
None,
)
if summary_up_to_msg_id and summary_position is None:
stored_summary = ""
summary_up_to_msg_id = 0
unsummarized = (
messages[summary_position + 1 :] if summary_position is not None else messages
)
binding = getattr(llm_config, "binding", None)
route = (
{"provider": binding, "model": llm_config.model} if isinstance(binding, str) else None
)
if os.getenv("DEEPTUTOR_CHAT_ENGINE") == "typescript-native":
from deeptutor.runtime.ts_engine.config import compatibility_reason
if not compatibility_reason(llm_config):
from .native_history import build_native_history
return await build_native_history(
self,
session_id=session_id,
llm_config=llm_config,
language=language,
messages=messages,
unsummarized=unsummarized,
summary=stored_summary,
route=route,
on_event=on_event,
)
current_history = self._build_history(stored_summary, unsummarized)
current_tokens = self._model_tokens(unsummarized, stored_summary, route)
previous_model_turn = next(
(record for row in reversed(messages) if (record := model_turn(row)) is not None),
None,
)
if current_tokens <= budget:
return ContextBuildResult(
conversation_history=current_history,
conversation_summary=stored_summary,
context_text=build_history_text(current_history),
events=[],
token_count=current_tokens,
budget=budget,
model_history=replay_history(unsummarized, stored_summary, route),
previous_model_turn=previous_model_turn,
)
older_unsummarized, recent_messages = self._select_recent_messages(
unsummarized, recent_budget, route=route
)
# Everything not retained verbatim: previously summarized messages
# plus the older unsummarized turns.
prefix_messages = messages[: len(messages) - len(recent_messages)]
prefix_transcript = format_messages_as_transcript(prefix_messages)
# Anti-drift: while the raw prefix still fits the rebuild budget,
# re-summarize from the original messages instead of folding the
# previous summary into itself — summary-of-summary loses detail
# monotonically. Only beyond that budget degrade to fold-in.
rebuild_from_raw = bool(prefix_transcript) and count_tokens(
prefix_transcript
) <= self._rebuild_source_budget(llm_config)
merge_parts: list[str] = []
if rebuild_from_raw:
merge_parts.append(f"Conversation history to summarize:\n{prefix_transcript}")
else:
if stored_summary:
merge_parts.append(f"Existing summary:\n{stored_summary}")
older_transcript = format_messages_as_transcript(older_unsummarized)
if older_transcript:
merge_parts.append(f"Older turns to fold in:\n{older_transcript}")
if not merge_parts and recent_messages:
merge_parts.append(format_messages_as_transcript(recent_messages))
summarize_ok = True
replay_request = None
if (
previous_model_turn
and older_unsummarized
and isinstance(previous_model_turn.get("system"), str)
):
# The current retained prefix is authoritative once model turns
# exist; legacy sessions keep their raw-transcript rebuild path.
replay_request = {
"messages": [
{"role": "system", "content": previous_model_turn["system"]},
*[
{key: value for key, value in message.items() if key != "_context_snapshot"}
for message in replay_history(older_unsummarized, stored_summary, route)
],
],
"tools": previous_model_turn.get("tools"),
"rows": older_unsummarized,
}
pending_summary = summary_snapshot(stored_summary)
if pending_summary is not None and not any(
message.get("content") == pending_summary["content"]
for message in replay_request["messages"]
):
replay_request["messages"].append(
{
key: value
for key, value in pending_summary.items()
if key != "_context_snapshot"
}
)
try:
self._summary_rows = older_unsummarized
self._summary_prior = stored_summary
summary_kwargs: dict[str, Any] = (
{"replay_request": replay_request} if replay_request else {}
)
new_summary, events = await self._summarize(
session_id=session_id,
language=language,
source_text="\n\n".join(part for part in merge_parts if part.strip()),
summary_budget=summary_budget,
on_event=on_event,
**summary_kwargs,
)
except Exception as exc:
summarize_ok = False
new_summary = ""
events = []
# Keep private transcript/provider details out of diagnostics.
logger.warning(
"Context condensation failed (%s); bounding recent history without advancing its watermark",
type(exc).__name__,
)
if summarize_ok and new_summary:
# Advance the watermark only on a successful summarize — never
# past turns that were not actually folded in.
up_to_msg_id = summary_up_to_msg_id
if prefix_messages:
up_to_msg_id = prefix_messages[-1].get("id", 0) or 0
await self.store.update_summary(session_id, new_summary, up_to_msg_id)
stored_summary = new_summary
retained_rows = recent_messages
else:
# Degrade for this turn only: keep the stale summary and as many
# unsummarized turns as fit; nothing is marked as summarized, so
# the next turn retries with the full material.
retained_rows = unsummarized
retained_groups = history_groups(retained_rows)
while (
len(retained_groups) > 1
and self._model_tokens(retained_rows, stored_summary, route) > budget
):
retained_groups.pop(0)
retained_rows = [row for group in retained_groups for row in group]
final_history = self._build_history(stored_summary, retained_rows)
final_text = build_history_text(final_history)
return ContextBuildResult(
conversation_history=final_history,
conversation_summary=stored_summary,
context_text=final_text,
events=events,
token_count=self._model_tokens(retained_rows, stored_summary, route),
budget=budget,
model_history=replay_history(retained_rows, stored_summary, route),
previous_model_turn=previous_model_turn,
)
__all__ = [
"ContextBuildResult",
"ContextBuilder",
"TRUNCATION_GUARD_RATIO",
"build_history_text",
"count_tokens",
"format_messages_as_transcript",
"extract_ask_user_clarifications",
"trim_incomplete_tail",
]