DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""
Turn-level runtime manager for unified chat streaming.
"""
from __future__ import annotations
import asyncio
from collections.abc import Callable, Sequence
from dataclasses import dataclass, field
import logging
import math
import re
from typing import TYPE_CHECKING, Any, Literal
import unicodedata
from deeptutor.core.stream import StreamEvent, StreamEventType
from deeptutor.services.llm.utils import clean_thinking_tags
from deeptutor.services.session.protocol import SessionStoreProtocol
from deeptutor.services.session.workspace_preferences import (
WORKSPACE_MODE_MASTERY,
WORKSPACE_MODES,
)
if TYPE_CHECKING:
from deeptutor.runtime.coordination import TurnLease
logger = logging.getLogger(__name__)
MemoryReference = Literal["recent", "profile", "scope", "preferences", "summary"]
# Content call_kinds that make up the persisted answer. The chat agent loop
# streams every round's text as ``content`` with ``agent_loop_round``, and all
# of it is the answer — the commentary a round wrote before calling a tool
# included. Published content is never retracted.
_ANSWER_CONTENT_CALL_KINDS = frozenset({"llm_final_response", "agent_loop_round"})
_FINAL_TURN_STATUSES = frozenset({"completed", "failed", "cancelled"})
def _should_capture_assistant_content(event: StreamEvent) -> bool:
if event.type != StreamEventType.CONTENT:
return False
metadata = event.metadata or {}
call_id = metadata.get("call_id")
if not call_id:
return True
return metadata.get("call_kind") in _ANSWER_CONTENT_CALL_KINDS
def _coerce_bool(value: Any, default: bool) -> bool:
if isinstance(value, bool):
return value
if isinstance(value, str):
normalized = value.strip().lower()
if normalized in {"true", "1", "yes", "on"}:
return True
if normalized in {"false", "0", "no", "off"}:
return False
return default
def _resolve_turn_outcome(
assistant_events: Sequence[dict[str, Any]],
done_event: StreamEvent | None,
) -> tuple[str, str]:
"""Resolve the persisted turn status and error from the terminal protocol."""
done_metadata = (done_event.metadata or {}) if done_event is not None else {}
status = str(done_metadata.get("status") or "completed")
if status not in _FINAL_TURN_STATUSES:
status = "completed"
error = ""
for event in reversed(assistant_events):
metadata = event.get("metadata")
metadata = metadata if isinstance(metadata, dict) else {}
if event.get("type") != StreamEventType.ERROR.value or not metadata.get("turn_terminal"):
continue
terminal_status = str(metadata.get("status") or "failed")
status = terminal_status if terminal_status in _FINAL_TURN_STATUSES else "failed"
if status == "completed":
status = "failed"
error = str(event.get("content") or "")
break
return status, error
def _resolve_turn_failure_metadata(
assistant_events: Sequence[dict[str, Any]],
) -> tuple[str, bool]:
"""Recover structured failure metadata from a terminal error event."""
for event in reversed(assistant_events):
metadata = event.get("metadata")
metadata = metadata if isinstance(metadata, dict) else {}
if event.get("type") != StreamEventType.ERROR.value or not metadata.get("turn_terminal"):
continue
code = str(metadata.get("error_code") or "")
retryable = _coerce_bool(metadata.get("retryable"), False)
return code, retryable
return "", False
def _assemble_persisted_answer(
content_segments: Sequence[tuple[str | None, str]],
) -> str:
"""Replay all published answer text, including commentary before tool calls."""
return clean_thinking_tags("".join(text for _call_id, text in content_segments))
_FENCED_CODE_BLOCK_RE = re.compile(r"```[\s\S]*?```")
_INLINE_CODE_SPAN_RE = re.compile(r"`[^`\n]*`")
_MATH_SPAN_RE = re.compile(
r"\\\[[\s\S]*?\\\]|\\\([\s\S]*?\\\)|\$\$[\s\S]*?\$\$|\$(?!\s)(?:\\.|[^$\n])*?(?<!\s)\$"
)
def _is_escaped(text: str, index: int) -> bool:
"""Whether the character at index has an odd-length backslash prefix."""
slash_count = 0
cursor = index - 1
while cursor >= 0 and text[cursor] == "\\":
slash_count += 1
cursor -= 1
return slash_count % 2 == 1
def _is_emphasis_normal_character(value: str | None) -> bool:
return bool(value and (value.isalpha() or value.isnumeric()))
def _is_emphasis_punctuation_or_symbol(value: str | None) -> bool:
return bool(value and unicodedata.category(value)[0] in {"P", "S"})
def _can_open_emphasis(line: str, index: int, marker: str) -> bool:
before = line[index - 1] if index else None
after_index = index + len(marker)
after = line[after_index] if after_index < len(line) else None
if after is None or after.isspace():
return False
if _is_emphasis_punctuation_or_symbol(after):
return (
before is None
or before.isspace()
or _is_emphasis_punctuation_or_symbol(before)
or _is_emphasis_normal_character(before)
)
return True
def _can_close_emphasis(line: str, index: int, marker: str) -> bool:
before = line[index - 1] if index else None
after_index = index + len(marker)
after = line[after_index] if after_index < len(line) else None
if before is None or before.isspace():
return False
if _is_emphasis_punctuation_or_symbol(before):
return (
after is None
or after.isspace()
or _is_emphasis_punctuation_or_symbol(after)
or _is_emphasis_normal_character(after)
)
return True
def _paired_emphasis_delimiters(line: str) -> list[tuple[str, int, int]]:
"""Return only syntactically plausible (marker, left opener, right closer) pairs."""
openers: dict[str, list[int]] = {"*": [], "**": []}
pairs: list[tuple[str, int, int]] = []
cursor = 0
while cursor < len(line):
if line[cursor] != "*" or _is_escaped(line, cursor):
cursor += 1
continue
run_end = cursor
while run_end < len(line) and line[run_end] == "*":
run_end += 1
marker = line[cursor:run_end]
if marker in openers:
can_open = _can_open_emphasis(line, cursor, marker)
can_close = _can_close_emphasis(line, cursor, marker)
if can_close and openers[marker]:
pairs.append((marker, openers[marker].pop(), cursor))
elif can_open:
openers[marker].append(cursor)
cursor = run_end
return pairs
def _repair_chinese_emphasis_line(line: str) -> str:
insertions: set[int] = set()
for marker, left_opener, right_closer in _paired_emphasis_delimiters(line):
left_before = line[left_opener - 1] if left_opener else None
left_inside = (
line[left_opener + len(marker)] if left_opener + len(marker) < len(line) else None
)
right_inside = line[right_closer - 1] if right_closer else None
right_after_index = right_closer + len(marker)
right_after = line[right_after_index] if right_after_index < len(line) else None
left_needs_space = _is_emphasis_normal_character(
left_before
) and _is_emphasis_punctuation_or_symbol(left_inside)
right_needs_space = _is_emphasis_punctuation_or_symbol(
right_inside
) and _is_emphasis_normal_character(right_after)
if left_needs_space:
insertions.add(left_opener)
if right_needs_space:
insertions.add(right_after_index)
# Only mirror a required repair onto the other marker in THIS pair.
if left_needs_space != right_needs_space:
if _is_emphasis_normal_character(right_inside) and _is_emphasis_normal_character(
right_after
):
insertions.add(right_after_index)
elif _is_emphasis_normal_character(left_before) and _is_emphasis_normal_character(
left_inside
):
insertions.add(left_opener)
for index in sorted(insertions, reverse=True):
line = f"{line[:index]} {line[index:]}"
return line
def _repair_chinese_emphasis_for_persistence(content: str, language: str) -> str:
"""Normalize CJK Markdown emphasis before the assistant answer is stored.
This deliberately runs only for Chinese model output and leaves code and
mathematics literal, so the persisted source matches its valid rendering.
"""
if not content or not str(language or "").lower().startswith("zh"):
return content
protected: list[str] = []
def mask(match: re.Match[str]) -> str:
protected.append(match.group(0))
return f"\x00CJK_PROTECTED_{len(protected) - 1}\x00"
masked = _FENCED_CODE_BLOCK_RE.sub(mask, content)
masked = _MATH_SPAN_RE.sub(mask, masked)
masked = _INLINE_CODE_SPAN_RE.sub(mask, masked)
repaired = "\n".join(_repair_chinese_emphasis_line(line) for line in masked.split("\n"))
return re.sub(
r"\x00CJK_PROTECTED_(\d+)\x00",
lambda match: protected[int(match.group(1))],
repaired,
)
def _stamp_content_offset(
payload_event: dict[str, Any],
assistant_content: str | Callable[[], str],
) -> None:
"""Attach the replay boundary to an event the answer must be laid out around.
A settled turn is reloaded from an event *preview* that carries no
``content`` events (see the web client's ``compactTracePreview``), so the
body has to be rebuilt from the persisted answer string. Without a mark
saying how much of that answer had been written when a row appeared, every
tool call and card would pile up at one end and the reload would not
resemble what the reader watched.
Three kinds of event carry the mark: a resolved ``ask_user`` card, the
start of a tool call, and a message the learner sent mid-turn that the
turn read. All are rendered between runs of answer text.
``assistant_content`` may be a callable: building the answer so far is a
join and a cleanup pass over every segment, and every streamed event comes
through here, so it is only built for the few events that need it.
"""
metadata = payload_event.get("metadata")
if not isinstance(metadata, dict):
return
anchors_layout = (
bool(metadata.get("ask_user_resolved"))
or metadata.get("trace_kind") == "user_input"
or payload_event.get("type") == StreamEventType.TOOL_CALL.value
)
if anchors_layout and "assistant_content_offset" not in metadata:
content = assistant_content() if callable(assistant_content) else assistant_content
metadata["assistant_content_offset"] = len(content)
def _clip_text(value: str, limit: int = 4000) -> str:
text = str(value or "").strip()
if len(text) <= limit:
return text
return text[:limit].rstrip() + "\n...[truncated]"
_TITLE_QUOTE_PAIRS: tuple[tuple[str, str], ...] = (
('"', '"'),
("'", "'"),
("“", "”"),
("‘", "’"),
("「", "」"),
("『", "』"),
("`", "`"),
)
_TITLE_PREFIXES: tuple[str, ...] = (
"Title:",
"title:",
"TITLE:",
"Title-",
"标题:",
"标题:",
"对话标题:",
"对话标题:",
)
_TITLE_TRAILING_PUNCT = ".。!!??,,;;、 \t"
_INTERRUPTED_TURN_ERROR = "Turn interrupted by server restart. Please retry your message."
#: Openings that mean the title model reported a failure instead of writing one.
#:
#: ``llm_stream`` surfaces a provider failure as streamed *content*, not as a
#: raised exception, so a bad key yields a perfectly well-formed short string —
#: which the sanitizer then trims and stores as the conversation's name, where
#: it stays forever and follows the session into every list that shows it. The
#: fallback path below (truncate the first user message) already handles "no
#: title"; this is what routes an error into it.
#: Every entry carries its own punctuation or is a word no title starts with.
#: A bare "error " would reject "Error handling in Rust", which is a perfectly
#: good name for a conversation — the guard must be cheaper to pass than a real
#: title is to lose.
_TITLE_ERROR_PREFIXES: tuple[str, ...] = (
"error:",
"[error",
"exception:",
"traceback",
"错误:",
"错误:",
"请求失败",
"调用失败",
)
def _looks_like_error_payload(text: str) -> bool:
"""Report whether a generated title is really a failure message.
Kept deliberately narrow. A real title is a handful of words naming a
subject; it does not open with an error label and is not a serialised
object. Anything broader risks discarding a legitimate title — the cost of
a false negative here is one ugly name, the cost of a false positive is a
good title silently replaced by a truncated question.
"""
candidate = text.strip()
if not candidate:
return False
if candidate[0] in "{[":
return True
lowered = candidate.lower()
return any(lowered.startswith(prefix) for prefix in _TITLE_ERROR_PREFIXES)
def _sanitize_session_title(raw: str) -> str:
"""Trim the noise LLMs love to add to short titles.
Strips model reasoning tags, surrounding quotes, leading "Title:" labels,
trailing punctuation, and Markdown bold/italic markers. Caps length at
80 characters so a chatty model can't blow past the sidebar layout.
"""
text = clean_thinking_tags(raw or "").strip()
if not text:
return ""
text = text.splitlines()[0].strip()
# Iterate until the text stops shrinking — models often nest the
# noise (e.g. ``**Title:** "Hello"``) so a single pass leaves
# leftover wrappers.
for _ in range(8):
prev = text
text = text.lstrip("*_#- \t").rstrip("*_ \t")
for prefix in _TITLE_PREFIXES:
if text.startswith(prefix):
text = text[len(prefix) :].strip()
break
for opener, closer in _TITLE_QUOTE_PAIRS:
if len(text) >= 2 and text.startswith(opener) and text.endswith(closer):
text = text[len(opener) : len(text) - len(closer)].strip()
break
text = text.rstrip(_TITLE_TRAILING_PUNCT)
if text == prev:
break
return text[:80]
def _extract_memory_references(payload: dict[str, Any]) -> list[MemoryReference]:
"""Return the L3 slot names the client opted in for this turn.
Any non-empty list triggers ``read_l3_concat`` injection in v2 — the
individual names are kept for forward-compat with workbench UI hints
(e.g. "I want preferences in this turn") even though the read tool
returns the full concat.
"""
refs = payload.get("memory_references", []) or []
if not isinstance(refs, list):
return []
allowed = {"recent", "profile", "scope", "preferences", "summary"}
out: list[MemoryReference] = []
for item in refs:
if item in allowed and item not in out:
out.append(item)
return out
def _string_list(value: Any) -> list[str]:
if not isinstance(value, list):
return []
return [item for item in value if isinstance(item, str) and item]
def _mastery_path_id(value: Any) -> str:
"""Normalize the optional session-to-mastery-path association."""
return str(value or "").strip()
_MASTERY_AGENTIC_ACTIONS = {
"chat",
"ask_questions",
"deep_solve",
# Backward-compatible top-level workspace capabilities.
"mastery_path",
"immersive_reading",
}
def _workspace_mode(value: Any, *, capability: str = "") -> str:
"""Normalize the stable workspace independently of the per-turn action.
Direct capability callers (including the CLI) can invoke Reading/Mastery
without a separate web workspace field, so those two values are also valid
request-boundary signals. Persisted sessions are upgraded by their store.
"""
candidate = str(value or "").strip()
if candidate in WORKSPACE_MODES:
return candidate
legacy = str(capability or "").strip()
return legacy if legacy in WORKSPACE_MODES else ""
def _mastery_loop_managed(workspace_mode: str, capability: str) -> bool:
"""Whether this action can mutate mastery state and therefore needs a lease."""
return workspace_mode == WORKSPACE_MODE_MASTERY and capability in _MASTERY_AGENTIC_ACTIONS
def _topic_material_manifest(path_id: str) -> tuple[str, dict[str, str]]:
"""Load a mastery topic's materials as (manifest, read_source index).
Storage-bound and synchronous; the caller runs it off the event loop. A
topic that cannot be loaded yields no manifest rather than failing the turn
— losing the materials degrades the lesson, losing the turn ends it.
"""
try:
from deeptutor.learning.storage import LearningStore
from deeptutor.learning.topic_materials import (
build_topic_materials,
render_topic_manifest,
)
store = LearningStore()
progress = store.load(path_id)
if progress is None:
return "", {}
topic = store.get_topic(path_id, progress=progress)
if topic is None or not topic.sources:
return "", {}
materials = build_topic_materials(topic.sources)
if materials.warnings:
logger.warning(
"Mastery topic %s: %d material(s) could not be loaded: %s",
path_id,
len(materials.warnings),
", ".join(materials.warnings),
)
return render_topic_manifest(materials)
except Exception:
logger.exception("Failed to build topic materials for mastery path %s", path_id)
return "", {}
def _reading_action_context(
material_id: str,
viewport: dict[str, Any],
question: str,
) -> str:
"""Bounded document evidence for non-agentic Reading actions."""
if not material_id:
return "The Reading workspace has no material open."
try:
from deeptutor.reading import ReadingStore, material_summary, search_material
store = ReadingStore()
manifest = store.manifest(material_id)
lines = [f"Open material: {material_summary(manifest)}"]
locator = int(viewport.get("locator") or 0)
selection = str(viewport.get("selection") or "").strip()
if selection:
lines.append(f"Selected quote at {manifest.unit} {locator or '?'}: {selection}")
if 1 <= locator <= manifest.unit_count:
visible = _clip_text(store.unit_text(material_id, locator), limit=5_000)
lines.append(f"Visible {manifest.unit} {locator}:\n{visible}")
result = search_material(store, material_id, question, limit=4)
if result.hits:
lines.append("Relevant matches:")
lines.extend(f"- {manifest.unit} {hit.locator}: {hit.snippet}" for hit in result.hits)
lines.append(f"Treat these excerpts as source evidence and cite {manifest.unit} locators.")
return "\n\n".join(lines)
except Exception:
logger.info("Reading action context unavailable for %s", material_id, exc_info=True)
return "The open Reading material is unavailable."
def _mastery_action_context(
path_id: str,
manifest: str,
source_index: dict[str, str],
) -> str:
"""Bounded topic/progress context for Quiz/Research/Visualize actions."""
if not path_id:
return ""
lines = [f"Mastery topic id: {path_id}"]
try:
from deeptutor.learning.storage import LearningStore
store = LearningStore()
progress = store.load(path_id)
topic = store.get_topic(path_id, progress=progress) if progress else None
if topic is not None:
lines.append(
f"Goal: {topic.metadata.goal or topic.metadata.description or progress.name}"
)
if progress is not None:
lines.append(f"Current learning stage: {progress.current_stage.value}")
module = next(
(item for item in progress.modules if item.id == progress.current_module_id),
None,
)
if module is not None:
lines.append(f"Current module: {module.name}")
if 0 <= progress.current_kp_index < len(module.knowledge_points):
lines.append(
"Current knowledge point: "
+ module.knowledge_points[progress.current_kp_index].name
)
except Exception:
logger.info("Mastery action state unavailable for %s", path_id, exc_info=True)
if manifest:
lines.append("Topic source manifest:\n" + manifest)
remaining = 12_000
excerpts: list[str] = []
for source_id, text in source_index.items():
if remaining <= 0:
break
excerpt = _clip_text(text, limit=min(4_000, remaining))
if excerpt:
excerpts.append(f"--- {source_id} ---\n{excerpt}")
remaining -= len(excerpt)
if excerpts:
lines.append("Topic source excerpts:\n" + "\n\n".join(excerpts))
lines.append(
"Use this topic as context for the requested action. Do not change mastery progress "
"unless the turn is running the guided tutor loop."
)
return "\n\n".join(lines)
# Reading material ids are content hashes or catalog-minted rm_ ids (a second
# copy of the same content gets its own catalog row, and the store resolves
# both to the same content directory); anything else is a client bug or an
# injection attempt, so the shape is enforced here rather than deeper in.
_READING_ID_RE = re.compile(r"^(?:[0-9a-f]{8,64}|rm_[0-9a-f]{12})$")
_READING_WORKSPACE_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
# A selection is quoted back into the prompt, so it is bounded here — the
# reader has no reason to send more, and a runaway selection must not eat the
# turn's context budget.
READING_SELECTION_MAX_CHARS = 2000
_TIMED_MEDIA_ID_RE = re.compile(r"^[0-9a-f]{16,64}$")
def _reading_material_id(value: Any) -> str:
"""Normalize the immersive-reading material bound to this turn."""
candidate = str(value or "").strip().lower()
return candidate if _READING_ID_RE.match(candidate) else ""
def _reading_material_revision(value: Any) -> int | None:
"""Normalize the immutable content revision displayed for this turn."""
try:
revision = int(value)
except (TypeError, ValueError):
return None
return revision if revision >= 1 else None
def _reading_workspace_id(value: Any) -> str:
"""Normalize the owner-scoped reading workspace bound to this turn."""
candidate = str(value or "").strip()
return candidate if _READING_WORKSPACE_ID_RE.fullmatch(candidate) else ""
def _reading_viewport(value: Any) -> dict[str, Any]:
"""Normalize what the reader reports it is showing.
Every field is optional: a freshly opened document has no locator yet, most
turns carry no selection, and only video materials report a playback time.
Absent keys are omitted rather than zeroed so the capability's prompt block
can distinguish "nothing selected" from an empty selection, and "no media
time" from a video paused at 0:00.
"""
if not isinstance(value, dict):
return {}
viewport: dict[str, Any] = {}
try:
locator = int(value.get("locator") or 0)
except (TypeError, ValueError):
locator = 0
if locator > 0:
viewport["locator"] = locator
selection = str(value.get("selection") or "").strip()
if selection:
viewport["selection"] = selection[:READING_SELECTION_MAX_CHARS]
raw_seconds = value.get("time_seconds")
if raw_seconds is not None and not isinstance(raw_seconds, bool):
try:
seconds = float(raw_seconds)
except (TypeError, ValueError):
seconds = -1.0
if math.isfinite(seconds) and seconds >= 0:
viewport["time_seconds"] = min(24 * 60 * 60, seconds)
return viewport
# Images attached per reading turn when the open page has embedded figures.
READING_VIEWPORT_MAX_IMAGES = 4
def _reading_viewport_page_render(material_id: str, locator: int) -> dict | None:
"""Thin wrapper over :func:`deeptutor.reading.page_render.page_render_record`.
The rendering rules (DPI, drawing gate, record shape) live in the reading
layer so the capability's viewport narration shares them; this name stays
for the session's attachment path.
"""
try:
from deeptutor.reading.page_render import page_render_record
return page_render_record(material_id, locator)
except Exception:
logger.warning("reading viewport page render failed", exc_info=True)
return None
def _reading_viewport_image_attachments(material_id: str, viewport: dict[str, Any]) -> list[dict]:
"""Attachments for the open page: its render first, embedded figures after.
A drawn page leads with the whole-page raster (the only way a vision model
sees a vector diagram); embedded rasters follow. The render consumes one of
the ``READING_VIEWPORT_MAX_IMAGES`` slots, and the total is capped there.
Pages that do not qualify fall back to the embedded-image records alone.
"""
viewport = viewport if isinstance(viewport, dict) else {}
embedded = _reading_viewport_image_records(material_id, viewport)
try:
locator = int(viewport.get("locator") or 0)
except (TypeError, ValueError):
locator = 0
if not material_id or locator <= 0:
return embedded[:READING_VIEWPORT_MAX_IMAGES]
rendered = _reading_viewport_page_render(material_id, locator)
if rendered is None:
return embedded[:READING_VIEWPORT_MAX_IMAGES]
return [rendered, *embedded[: READING_VIEWPORT_MAX_IMAGES - 1]]
def _reading_viewport_image_records(material_id: str, viewport: dict[str, Any]) -> list[dict]:
"""Image attachment records for the figures on the currently open page."""
try:
locator = int(viewport.get("locator") or 0)
except (TypeError, ValueError):
locator = 0
if not material_id or locator <= 0:
return []
try:
import base64
from deeptutor.reading import ReadingStore
store = ReadingStore()
rows = store.media_items_at(material_id, locator)
records: list[dict] = []
for index, row in enumerate(rows[:READING_VIEWPORT_MAX_IMAGES], start=1):
path = store.media_path(material_id, str(row.get("name") or ""))
if path is None:
continue
records.append(
{
"type": "image",
"url": "",
"base64": base64.b64encode(path.read_bytes()).decode("ascii"),
"filename": str(row.get("name") or f"image-{index}.png"),
"mime_type": str(row.get("mime") or "image/png"),
"id": f"rv-{material_id[:12]}-{locator}-{index}",
"embedded": True,
}
)
return records
except Exception:
logger.warning("reading viewport image lookup failed", exc_info=True)
return []
def _timed_media_id(value: Any) -> str:
candidate = str(value or "").strip().lower()
return candidate if _TIMED_MEDIA_ID_RE.fullmatch(candidate) else ""
def _timed_media_viewport(value: Any) -> dict[str, float]:
if not isinstance(value, dict):
return {}
try:
seconds = float(value.get("time_seconds") or 0)
except (TypeError, ValueError):
return {}
return {"time_seconds": min(24 * 60 * 60, max(0.0, seconds))}
def _reading_references(value: Any) -> list[dict[str, Any]]:
"""Normalize reading units explicitly attached to an ordinary chat turn."""
if not value:
return []
from deeptutor.modules.catalog import require_module
require_module("reading")
from deeptutor.reading.references import normalize_reading_references
return normalize_reading_references(value)
def _llm_selection_dict(value: Any) -> dict[str, str] | None:
from deeptutor.services.model_selection import LLMSelection
selection = LLMSelection.from_payload(value)
return selection.to_dict() if selection else None
def _partner_group_references(value: Any) -> list[dict[str, str]]:
"""Normalize the structured home-chat reference contract."""
if not isinstance(value, list):
return []
references: list[dict[str, str]] = []
seen: set[tuple[str, str]] = set()
for raw in value[:20]:
if not isinstance(raw, dict):
continue
group_id = str(raw.get("group_id") or "").strip()[:80]
session_key = str(raw.get("session_key") or "").strip()[:120]
key = (group_id, session_key)
if not all(key) or key in seen:
continue
seen.add(key)
references.append({"group_id": group_id, "session_key": session_key})
return references
def _note_generation(value: Any) -> dict[str, str] | None:
"""The learning block a turn fills in, in its wire shape, or None."""
if not isinstance(value, dict) or not value.get("block_id"):
return None
return {"block_id": str(value["block_id"]), "kind": str(value.get("kind") or "")}
def _request_snapshot_metadata(
*,
payload: dict[str, Any],
content: str,
capability: str,
config: dict[str, Any],
attachments: list[dict[str, Any]],
notebook_references: list[Any],
history_references: list[Any],
partner_group_references: list[dict[str, str]],
question_notebook_references: list[Any],
book_references: list[Any],
reading_references: Sequence[dict[str, Any]] = (),
persona: str,
memory_references: Sequence[str],
llm_selection: dict[str, str] | None,
) -> dict[str, Any]:
"""Persist the front-end context chips with the user message."""
snapshot: dict[str, Any] = {
"content": content,
"capability": capability,
"enabledTools": _string_list(payload.get("tools")),
"knowledgeBases": _string_list(payload.get("knowledge_bases")),
"language": str(payload.get("language", "en") or "en"),
# Keep empty values too. A failed turn can be resent after the
# conversation preferences have changed; absence would otherwise
# cause the retry to pick up the newer tools, sources, or persona.
"config": dict(config),
"notebookReferences": list(notebook_references),
"historyReferences": list(history_references),
"partnerGroupReferences": list(partner_group_references),
"questionNotebookReferences": list(question_notebook_references),
"bookReferences": list(book_references),
"readingReferences": list(reading_references),
"memoryReferences": list(memory_references),
"skills": _string_list(payload.get("skills")),
"mcp": _string_list(payload.get("mcp")),
"persona": persona,
}
for payload_key, snapshot_key in (
("workspace_id", "workspaceId"),
("mastery_session_mode", "masterySessionMode"),
("auto_route", "autoRoute"),
):
if payload_key in payload:
snapshot[snapshot_key] = payload[payload_key]
for payload_key, snapshot_key in (
("consult_partner_id", "consultPartnerId"),
("partner_discussion_group_id", "partnerDiscussionGroupId"),
("answer_by", "answerBy"),
):
if payload_key in payload:
snapshot[snapshot_key] = payload[payload_key]
workspace_mode = _workspace_mode(payload.get("workspace_mode"), capability=capability)
snapshot["workspaceMode"] = workspace_mode
if payload.get("capability_once"):
# Kept so a regenerate runs in this mode again without adopting it.
snapshot["capabilityOnce"] = True
if attachments:
snapshot["attachments"] = attachments
capability_route = payload.get("capability_route")
if isinstance(capability_route, dict):
snapshot["capabilityRoute"] = dict(capability_route)
mastery_path_id = _mastery_path_id(payload.get("mastery_path_id"))
snapshot["masteryPathId"] = mastery_path_id
for payload_key, snapshot_key in (
("mastery_answer", "masteryAnswer"),
("mastery_skip", "masterySkip"),
):
value = payload.get(payload_key)
if isinstance(value, dict) and value.get("question_id"):
snapshot[snapshot_key] = dict(value)
# Persisted so a regenerate re-runs with the same document open. Without it
# the reading capability would be inactive on the retry and the answer would
# silently lose its grounding.
reading_material_id = _reading_material_id(payload.get("reading_material_id"))
if reading_material_id:
snapshot["readingMaterialId"] = reading_material_id
reading_material_revision = _reading_material_revision(
payload.get("reading_material_revision")
)
if reading_material_revision is not None:
snapshot["readingMaterialRevision"] = reading_material_revision
reading_workspace_id = _reading_workspace_id(payload.get("reading_workspace_id"))
snapshot["readingWorkspaceId"] = reading_workspace_id
# The passage the question was asked about. Without it the bubble shows a
# bare "Explain this" with nothing to say what "this" was, and a
# regenerate re-asks it about no passage at all.
viewport = _reading_viewport(payload.get("reading_viewport"))
if reading_material_id and viewport.get("selection"):
snapshot["readingSelection"] = {
"quote": viewport["selection"],
"locator": viewport.get("locator", 0),
}
timed_media_id = _timed_media_id(payload.get("timed_media_id"))
if timed_media_id:
snapshot["timedMediaId"] = timed_media_id
# A note companion turn is bound to its page, and a block's "Generate" to
# that block: a regenerate has to fill the same block on the same page.
note_document_id = str(payload.get("note_document_id") or "")
if note_document_id:
snapshot["noteDocumentId"] = note_document_id
note_generation = _note_generation(payload.get("note_generation"))
if note_generation:
snapshot["noteGeneration"] = note_generation
if llm_selection:
snapshot["llmSelection"] = llm_selection
metadata: dict[str, Any] = {"request_snapshot": snapshot}
client_submission_id = payload.get("client_submission_id")
if isinstance(client_submission_id, str) and client_submission_id:
metadata["client_submission_id"] = client_submission_id
return metadata
def _format_question_bank_entry(entry: dict[str, Any]) -> str:
"""Render a single Question Bank entry as a structured Markdown block."""
lines: list[str] = []
title = str(entry.get("session_title", "") or "Untitled session")
difficulty = str(entry.get("difficulty", "") or "").strip()
qtype = str(entry.get("question_type", "") or "").strip()
is_correct = bool(entry.get("is_correct"))
badges: list[str] = []
if qtype:
badges.append(qtype)
if difficulty:
badges.append(difficulty)
badges.append("correct" if is_correct else "incorrect")
badge_text = " · ".join(badges)
lines.append(f"### Question (from {title}) [{badge_text}]")
lines.append(_clip_text(str(entry.get("question", "") or ""), limit=2000))
options = entry.get("options") or {}
if isinstance(options, dict) and options:
lines.append("")
lines.append("**Options:**")
for key in sorted(options.keys()):
lines.append(f"- {key}. {options[key]}")
user_answer = str(entry.get("user_answer", "") or "").strip()
correct_answer = str(entry.get("correct_answer", "") or "").strip()
if user_answer:
lines.append("")
lines.append(f"**User's Answer:** {_clip_text(user_answer, limit=1000)}")
if correct_answer:
lines.append(f"**Reference Answer:** {_clip_text(correct_answer, limit=1500)}")
explanation = str(entry.get("explanation", "") or "").strip()
if explanation:
lines.append("")
lines.append("**Explanation:**")
lines.append(_clip_text(explanation, limit=2000))
return "\n".join(lines)
async def _count_branch_user_turns(
store: SessionStoreProtocol,
session_id: str,
leaf_message_id: int | None,
) -> int:
"""Count user messages on the active branch's ancestor chain.
Used by the chat source inventory to assign ``first_seen_turn`` for
*fresh* sources (= current turn = past_user_turns + 1). When
``leaf_message_id`` is ``None`` (legacy linear append) all messages
in the session are counted; otherwise we walk the
``parent_message_id`` chain so sibling branches don't inflate the
count. Kept tiny and protocol-only (``get_messages``) so it stays
compatible with every store backend.
"""
all_msgs = await store.get_messages(session_id)
if leaf_message_id is None:
return sum(1 for m in all_msgs if m.get("role") == "user")
by_id: dict[int, dict[str, Any]] = {}
for m in all_msgs:
mid = m.get("id")
if mid is not None:
by_id[int(mid)] = m
count = 0
current: int | None = int(leaf_message_id)
safety = 10_000
while current is not None and safety > 0:
m = by_id.get(int(current))
if m is None:
break
if m.get("role") == "user":
count += 1
parent = m.get("parent_message_id")
current = int(parent) if parent is not None else None
safety -= 1
return count
async def _build_question_bank_context(
store: SessionStoreProtocol,
entry_ids: list[Any],
) -> str:
"""Fetch the requested Question Bank entries and render them as context."""
get_entry = getattr(store, "get_notebook_entry", None)
if not callable(get_entry):
return ""
seen: set[int] = set()
blocks: list[str] = []
for raw in entry_ids:
try:
entry_id = int(raw)
except (TypeError, ValueError):
continue
if entry_id in seen:
continue
seen.add(entry_id)
try:
entry = await get_entry(entry_id)
except Exception:
entry = None
if not entry:
continue
blocks.append(_format_question_bank_entry(entry))
return "\n\n---\n\n".join(blocks)
def _normalize_filename_list(raw: dict[str, Any]) -> list[str]:
"""Coalesce legacy single-filename and modern multi-filename inputs.
Returns the cleaned list (possibly empty). Empty / whitespace-only
entries are dropped, and the singular ``user_answer_image_filename``
is honoured as a fallback so older clients still surface their
filename in the system prompt.
"""
candidates: list[Any] = []
plural = raw.get("user_answer_image_filenames")
if isinstance(plural, list):
candidates.extend(plural)
elif isinstance(plural, str):
candidates.append(plural)
legacy = raw.get("user_answer_image_filename")
if isinstance(legacy, str) and legacy.strip():
candidates.append(legacy)
cleaned: list[str] = []
for item in candidates:
if not isinstance(item, str):
continue
name = item.strip()
if name:
cleaned.append(name)
return cleaned
def _extract_followup_question_context(
config: dict[str, Any] | None,
) -> dict[str, Any] | None:
if not isinstance(config, dict):
return None
raw = config.pop("followup_question_context", None)
if not isinstance(raw, dict):
return None
question = str(raw.get("question", "") or "").strip()
question_id = str(raw.get("question_id", "") or "").strip()
if not question:
return None
options = raw.get("options")
normalized_options: dict[str, str] | None = None
if isinstance(options, dict):
normalized_options = {
str(key).strip().upper()[:1]: str(value or "").strip()
for key, value in options.items()
if str(value or "").strip()
}
return {
"parent_quiz_session_id": str(raw.get("parent_quiz_session_id", "") or "").strip(),
"question_id": question_id,
"question": question,
"question_type": str(raw.get("question_type", "") or "").strip(),
"options": normalized_options,
"correct_answer": str(raw.get("correct_answer", "") or "").strip(),
"explanation": str(raw.get("explanation", "") or "").strip(),
"difficulty": str(raw.get("difficulty", "") or "").strip(),
"concentration": str(raw.get("concentration", "") or "").strip(),
"knowledge_context": _clip_text(str(raw.get("knowledge_context", "") or "").strip()),
"user_answer": str(raw.get("user_answer", "") or "").strip(),
"is_correct": raw.get("is_correct"),
# Filenames of the learner's image answers, when any were attached.
# The bytes are sent as regular WS attachments on the first
# follow-up turn — we just record the filenames here so the system
# prompt can tell the LLM *what* those attached images actually
# are. Accept both the legacy single ``user_answer_image_filename``
# string and the new ``user_answer_image_filenames`` list.
"user_answer_image_filenames": _normalize_filename_list(raw),
# Most recent AI-judge output the learner saw, if they ran the
# judge. Forwarded so the follow-up tutor can build on the same
# assessment rather than starting fresh.
"ai_judgment": _clip_text(str(raw.get("ai_judgment", "") or "").strip()),
}
# A side chat reads the whole parent conversation, newest turns first, until
# this budget is spent; each message is clipped so one long answer cannot
# crowd out the rest.
SIDE_CHAT_TRANSCRIPT_MAX_CHARS = 24_000
SIDE_CHAT_MESSAGE_MAX_CHARS = 6_000
def _extract_side_chat_context(
config: dict[str, Any] | None,
) -> dict[str, Any] | None:
"""Remove and normalize what a side chat is about: its parent conversation.
The wire key is still ``selection_tutor_context`` from when the side thread
tutored one selected passage. A selection now reaches a side chat the way
it reaches any chat — as a quote attachment — so the context only names
the parent and the tip of the branch the learner was looking at.
"""
if not isinstance(config, dict):
return None
raw = config.pop("selection_tutor_context", None)
if not isinstance(raw, dict):
return None
if raw.get("selected_text") and raw.get("scope") != "conversation":
return _extract_selection_tutor_context({"selection_tutor_context": raw})
parent_session_id = str(raw.get("parent_session_id", "") or "").strip()
if not parent_session_id:
return None
context: dict[str, Any] = {"parent_session_id": parent_session_id}
raw_leaf = raw.get("source_message_id")
leaf: int | None = None
if isinstance(raw_leaf, int) and not isinstance(raw_leaf, bool):
leaf = raw_leaf
elif str(raw_leaf or "").strip().isdigit():
leaf = int(str(raw_leaf).strip())
# Edit branches the learner moved away from are not part of what they are
# asking about.
if leaf is not None and leaf > 0:
context["source_message_id"] = leaf
return context
def _side_chat_transcript(messages: list[dict[str, Any]]) -> list[dict[str, str]]:
"""The parent conversation a side chat reads, bounded from the newest end."""
kept: list[dict[str, str]] = []
spent = 0
for message in reversed(messages):
role = str(message.get("role") or "").strip()
content = str(message.get("content") or "").strip()
if role not in {"user", "assistant"} or not content:
continue
content = _clip_text(content, limit=SIDE_CHAT_MESSAGE_MAX_CHARS)
if kept and spent + len(content) > SIDE_CHAT_TRANSCRIPT_MAX_CHARS:
kept.append({"role": "omitted", "content": ""})
break
kept.append({"role": role, "content": content})
spent += len(content)
kept.reverse()
return kept
async def _resolve_side_chat_context(
store: Any,
context: dict[str, Any],
) -> dict[str, Any]:
"""Read the parent conversation a side chat is about, fresh every turn so
the thread never answers from a stale copy."""
if context.get("selected_text"):
return await _resolve_selection_tutor_context(store, context)
resolved = dict(context)
leaf = resolved.get("source_message_id")
try:
path = await store.get_messages_for_context(
str(resolved.get("parent_session_id") or ""),
leaf if isinstance(leaf, int) and leaf > 0 else None,
)
except Exception:
raise ValueError("Could not read the conversation this side chat is about") from None
resolved["conversation_messages"] = _side_chat_transcript(path)
return resolved
def _extract_persist_user_message(config: dict[str, Any] | None) -> bool:
if not isinstance(config, dict):
return True
raw = config.pop("_persist_user_message", True)
if isinstance(raw, bool):
return raw
if isinstance(raw, str):
return raw.strip().lower() not in {"false", "0", "no"}
return bool(raw)
def _extract_regenerate_flag(config: dict[str, Any] | None) -> bool:
if not isinstance(config, dict):
return False
raw = config.pop("_regenerate", False)
if isinstance(raw, bool):
return raw
if isinstance(raw, str):
return raw.strip().lower() in {"true", "1", "yes"}
return bool(raw)
def _format_followup_question_context(context: dict[str, Any], language: str = "en") -> str:
options = context.get("options") or {}
option_lines = []
if isinstance(options, dict) and options:
for key, value in options.items():
if value:
option_lines.append(f"{key}. {value}")
correctness = context.get("is_correct")
correctness_text = (
"correct" if correctness is True else "incorrect" if correctness is False else "unknown"
)
if str(language or "en").lower().startswith("zh"):
lines = [
"你正在处理一道测验题的后续追问。",
"下面是本题上下文,请在后续回答中优先围绕这道题进行解释、纠错、延展和追问。",
"如果用户提出超出本题的内容,也可以正常回答,但要保持和本题的连续性。",
"",
"[Question Follow-up Context]",
f"Question ID: {context.get('question_id') or '(none)'}",
f"Parent quiz session: {context.get('parent_quiz_session_id') or '(none)'}",
f"Question type: {context.get('question_type') or '(none)'}",
f"Difficulty: {context.get('difficulty') or '(none)'}",
f"Concentration: {context.get('concentration') or '(none)'}",
"",
"Question:",
context.get("question") or "(none)",
]
if option_lines:
lines.extend(["", "Options:", *option_lines])
lines.extend(
[
"",
f"User answer: {context.get('user_answer') or '(not provided)'}",
f"User result: {correctness_text}",
f"Reference answer: {context.get('correct_answer') or '(none)'}",
"",
"Explanation:",
context.get("explanation") or "(none)",
]
)
image_filenames = context.get("user_answer_image_filenames") or []
if isinstance(image_filenames, list) and image_filenames:
filename_text = "、".join(image_filenames)
count_text = f"{len(image_filenames)} 张" if len(image_filenames) > 1 else "一张"
lines.extend(
[
"",
"学习者作答附图:",
f"该作答共附了{count_text}图片(文件名:{filename_text}),"
f"随首条追问消息一起发送,是用户提交的作答内容的一部分,不是无关上下文。"
f"请结合图片中的文字/公式/草图进行解读,并将其视为对上面 “User answer” 文本的补充。",
]
)
ai_judgment = context.get("ai_judgment")
if ai_judgment:
lines.extend(
[
"",
"AI 评判(之前已对学习者作答给出的评判,请基于此继续,不要重复完整重写):",
ai_judgment,
]
)
if context.get("knowledge_context"):
lines.extend(
[
"",
"Knowledge context:",
context["knowledge_context"],
]
)
return "\n".join(lines).strip()
lines = [
"You are handling follow-up questions about a single quiz item.",
"Use the question context below as the primary grounding for future turns in this session.",
"If the user asks something broader, you may answer normally, but maintain continuity with this quiz item.",
"",
"[Question Follow-up Context]",
f"Question ID: {context.get('question_id') or '(none)'}",
f"Parent quiz session: {context.get('parent_quiz_session_id') or '(none)'}",
f"Question type: {context.get('question_type') or '(none)'}",
f"Difficulty: {context.get('difficulty') or '(none)'}",
f"Concentration: {context.get('concentration') or '(none)'}",
"",
"Question:",
context.get("question") or "(none)",
]
if option_lines:
lines.extend(["", "Options:", *option_lines])
lines.extend(
[
"",
f"User answer: {context.get('user_answer') or '(not provided)'}",
f"User result: {correctness_text}",
f"Reference answer: {context.get('correct_answer') or '(none)'}",
"",
"Explanation:",
context.get("explanation") or "(none)",
]
)
image_filenames = context.get("user_answer_image_filenames") or []
if isinstance(image_filenames, list) and image_filenames:
joined = ", ".join(image_filenames)
plural = "images were" if len(image_filenames) > 1 else "image was"
plural_noun = (
"Learner answer images" if len(image_filenames) > 1 else "Learner answer image"
)
lines.extend(
[
"",
f"{plural_noun}:",
f"{len(image_filenames)} {plural} attached to the first follow-up message "
f"(filenames: {joined}). They are part of the learner's answer — read their "
"text/formulas/sketches and treat them as a supplement to the typed `User answer` "
"above, not unrelated context.",
]
)
ai_judgment = context.get("ai_judgment")
if ai_judgment:
lines.extend(
[
"",
"Prior AI judgment (already shown to the learner — build on it instead of restating it in full):",
ai_judgment,
]
)
if context.get("knowledge_context"):
lines.extend(
[
"",
"Knowledge context:",
context["knowledge_context"],
]
)
return "\n".join(lines).strip()
def _format_side_chat_context(context: dict[str, Any], language: str = "en") -> str:
if context.get("selected_text"):
return _format_selection_tutor_context(context, language)
parent_session_id = str(context.get("parent_session_id") or "").strip() or "(none)"
messages = context.get("conversation_messages") or []
zh = str(language or "en").lower().startswith("zh")
if zh:
lines = [
"你是侧栏中的 Dito。学习者在主对话旁边开了一个侧边聊天,想在不打断主对话的前提下追问。",
"下面的主对话记录是这里所有问题的共同背景;“这个/刚才/上面”默认指主对话里的内容;学习者引用的段落是他们这一问具体指的地方。",
"优先依据主对话里已有的定义、推导、代码和结论回答;主对话没有提供的信息不要臆造,需要时说明这超出了主对话的范围。",
"不要读取、引用或写入全局记忆;这里的问答不会写回主对话。",
"回答要简明、循序渐进。",
"",
"[主对话记录(按时间顺序)]",
]
labels = {"user": "学习者", "assistant": "导师", "omitted": "(更早的消息已省略)"}
else:
lines = [
"You are Dito in a sidebar. The learner opened a side chat next to the main conversation to ask follow-up questions without interrupting it.",
"The main conversation below is the shared background for every question here; 'this', 'that', or 'above' refer to it by default, and a passage the learner quotes is what that question is about.",
"Ground answers in the definitions, derivations, code, and conclusions the main conversation already has. Do not invent what it does not contain; say so when a question goes beyond it.",
"Do not read, cite, or write global memory. Nothing said here is written back into the main conversation.",
"Answer clearly and step by step.",
"",
"[Main conversation, oldest first]",
]
labels = {"user": "Learner", "assistant": "Tutor", "omitted": "(earlier messages omitted)"}
if not messages:
lines.append("(主对话还没有内容)" if zh else "(the main conversation is still empty)")
for message in messages:
role = str(message.get("role") or "")
if role == "omitted":
lines.append(labels["omitted"])
continue
lines.extend([f"{labels.get(role, role)}:", str(message.get("content") or ""), ""])
lines.extend(
["", f"来源会话:{parent_session_id}" if zh else f"Source session: {parent_session_id}"]
)
return "\n".join(lines).strip()
@dataclass
class _LiveSubscriber:
queue: asyncio.Queue[dict[str, Any]]
@dataclass
class _TurnExecution:
turn_id: str
session_id: str
capability: str
payload: dict[str, Any]
task: asyncio.Task[None] | None = None
# True while the turn is parked inside ``ask_user`` waiting for a learner
# reply. Such a turn holds its resources (notably a mastery path lease)
# but is doing no work, so another turn may take over from it.
awaiting_user_reply: bool = False
subscribers: list[_LiveSubscriber] = field(default_factory=list)
events: list[dict[str, Any]] = field(default_factory=list)
next_seq: int = 1
flush_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
flush_task: asyncio.Task[None] | None = None
events_persisted: bool = False
persisted_events: list[dict[str, Any]] = field(default_factory=list)
events_flushed: bool = False
lease: TurnLease | None = None
coordination_task: asyncio.Task[None] | None = None
lease_lost: bool = False
shutdown_requested: bool = False
# Compatibility for saved requests and clients using passage-based tutoring.
SELECTION_TUTOR_MAX_CHARS = 12_000
def _extract_selection_tutor_context(
config: dict[str, Any] | None,
) -> dict[str, Any] | None:
"""Remove and normalize context for the Little Tutor side thread.
Two scopes share the thread: ``selection`` tutors one passage the learner
selected, ``conversation`` is a side chat about the whole parent
conversation and needs only that parent.
"""
if not isinstance(config, dict):
return None
raw = config.pop("selection_tutor_context", None)
if not isinstance(raw, dict):
return None
parent_session_id = str(raw.get("parent_session_id", "") or "").strip()
raw_source_message_id = raw.get("source_message_id")
source_message_id: int | None = None
if isinstance(raw_source_message_id, int) and not isinstance(raw_source_message_id, bool):
source_message_id = raw_source_message_id
elif str(raw_source_message_id or "").strip().isdigit():
source_message_id = int(str(raw_source_message_id).strip())
if str(raw.get("scope", "") or "").strip() == "conversation":
if not parent_session_id:
return None
conversation: dict[str, Any] = {
"scope": "conversation",
"selected_text": "",
"parent_session_id": parent_session_id,
}
# The tip of the branch the learner is looking at; edit branches they
# moved away from are not part of what they are asking about.
if source_message_id is not None and source_message_id > 0:
conversation["source_message_id"] = source_message_id
return conversation
selected_text = _clip_text(
str(raw.get("selected_text", "") or "").strip(),
limit=SELECTION_TUTOR_MAX_CHARS,
)
if not selected_text:
return None
context: dict[str, Any] = {
"selected_text": selected_text,
"parent_session_id": parent_session_id,
}
if source_message_id is not None:
context["source_message_id"] = source_message_id
source_message_text = str(raw.get("source_message_text", "") or "").strip()
if source_message_text:
context["source_message_text"] = source_message_text
source_message_role = str(raw.get("source_message_role", "") or "").strip()
if source_message_role in {"user", "assistant", "system"}:
context["source_message_role"] = source_message_role
return context
def _selection_source_excerpt(
source_text: str,
selected_text: str,
*,
limit: int = 12_000,
) -> str:
"""Bound a source message while keeping the selected passage in view."""
text = str(source_text or "").strip()
if len(text) <= limit:
return text
needle = str(selected_text or "").strip()
selection_start = _selection_start(text, needle) if needle else -1
if selection_start < 0:
return _clip_text(text, limit=limit)
before = max(1_000, (limit - len(needle)) // 2)
start = max(0, selection_start - before)
end = min(len(text), start + limit)
selection_end = min(len(text), selection_start + max(len(needle), 1))
if selection_end > end:
end = selection_end
start = max(0, end - limit)
excerpt = text[start:end]
if start > 0:
excerpt = "[earlier content omitted]\n" + excerpt
if end < len(text):
excerpt += "\n[later content omitted]"
return excerpt
def _selected_latex_body(selected: str) -> str | None:
"""Return the body of a complete Markdown math selection, if any."""
match = re.fullmatch(r"\$\$(.+?)\$\$|\$(.+?)\$", selected, flags=re.DOTALL)
if not match:
return None
body = " ".join((match.group(1) or match.group(2) or "").split())
if not body:
return None
# Restrict delimiter equivalence to content that plausibly came from a
# rendered formula. Ordinary prose selections still require an exact match.
if not re.search(r"\\[A-Za-z]+|[_^=+*/<>-]", body):
return None
return body
def _selection_start(source: str, selected: str) -> int:
"""Find an exact selection, or its equivalent LaTeX body, in source text."""
start = source.find(selected) if selected else -1
if start >= 0:
return start
body = _selected_latex_body(selected)
if body is None:
return -1
pattern = r"\s+".join(re.escape(part) for part in body.split(" "))
match = re.search(pattern, source, flags=re.DOTALL)
return match.start() if match else -1
def _latex_selection_is_grounded(source: str, selected: str) -> bool:
"""Whether selected KaTeX LaTeX has an equivalent body in the source.
The browser maps a rendered formula back to Markdown ``$...$`` delimiters.
The authoritative message may instead contain multiline ``$$`` fences,
bracket/parenthesis delimiters, a code span, or bare LaTeX. Comparing the
formula body keeps the check content-bound while allowing those display
representations to differ.
"""
body = _selected_latex_body(selected)
if body is None:
return False
normalized_source = " ".join(source.split())
return body in normalized_source
def _selection_is_grounded(source_text: str, selected_text: str) -> bool:
"""Whether the claimed selection occurs in its containing message."""
source = str(source_text or "")
selected = str(selected_text or "").strip()
if not source or not selected:
return False
if selected in source:
return True
# Browser selections collapse rendered whitespace while the stored source
# preserves Markdown/code layout. Permit that representational difference,
# but never accept text that is absent from the authoritative message.
normalized_source = " ".join(source.split())
normalized_selected = " ".join(selected.split())
if normalized_selected and normalized_selected in normalized_source:
return True
return _latex_selection_is_grounded(normalized_source, normalized_selected)
async def _resolve_selection_tutor_context(
store: Any,
context: dict[str, Any],
) -> dict[str, Any]:
"""Resolve what a Little Tutor thread is grounded in, from its parent chat.
A selection resolves to its containing message; a side chat resolves to
the parent conversation itself. Both are read fresh every turn so the
thread never answers from a stale copy.
"""
resolved = dict(context)
parent_session_id = str(resolved.get("parent_session_id") or "").strip()
if resolved.get("scope") == "conversation":
leaf = resolved.get("source_message_id")
try:
path = await store.get_messages_for_context(
parent_session_id,
leaf if isinstance(leaf, int) and leaf > 0 else None,
)
except Exception:
raise ValueError("Could not read the conversation this side chat is about") from None
resolved["conversation_messages"] = _side_chat_transcript(path)
return resolved
source_message_id = resolved.get("source_message_id")
authoritative_source_required = bool(
parent_session_id and isinstance(source_message_id, int) and source_message_id > 0
)
source_message = None
if authoritative_source_required:
try:
path = await store.get_messages_for_context(
parent_session_id,
source_message_id,
)
except Exception:
raise ValueError("Could not resolve the selected text's source message") from None
else:
source_message = next(
(
message
for message in reversed(path)
if str(message.get("id")) == str(source_message_id)
),
None,
)
if source_message is None:
raise ValueError("The selected text's source message was not found")
resolved["source_message_text"] = str(source_message.get("content") or "").strip()
role = str(source_message.get("role") or "").strip()
if role in {"user", "assistant", "system"}:
resolved["source_message_role"] = role
source_text = str(resolved.get("source_message_text") or "").strip()
selected_text = str(resolved.get("selected_text") or "")
if not _selection_is_grounded(source_text, selected_text):
qualifier = "authoritative " if authoritative_source_required else ""
raise ValueError(f"Selected text was not found in the {qualifier}source message")
resolved["source_message_text"] = _selection_source_excerpt(
source_text,
selected_text,
)
return resolved
def _format_selection_tutor_context(context: dict[str, Any], language: str = "en") -> str:
if context.get("scope") == "conversation":
return _format_side_chat_context(context, language=language)
selected_text = context.get("selected_text", "").strip()
parent_session_id = context.get("parent_session_id", "").strip() or "(none)"
source_message_text = str(context.get("source_message_text") or "").strip()
source_message_role = str(context.get("source_message_role") or "").strip()
if str(language or "en").lower().startswith("zh"):
lines = [
"你是侧栏中的“小老师”,负责回答学习者对聊天内容的局部追问。",
"用户精确选中的文字是当前问题的直接指代;原消息上下文只用于解释该选中内容在此处的具体含义。",
"优先依据原消息中的定义、代码、前后句和符号关系回答,不要把短变量名脱离上下文解释成其他缩写。",
"不要读取、引用或写入全局记忆;不要把用户问题里的“这个/它/上述内容”解释成记忆系统。",
"如果先前回答偏离了选中内容,请明确纠正并回到选中内容本身。",
"回答当前问题时要简明、循序渐进;原消息没有提供的信息不要臆造。",
]
if source_message_text:
role_label = source_message_role or "unknown"
lines.extend(
[
"",
"[原消息上下文]",
f"消息角色:{role_label}",
source_message_text,
"",
"[用户精确选中的内容]",
selected_text,
]
)
else:
lines.extend(["", "[选中内容]", selected_text])
lines.extend(["", f"来源会话:{parent_session_id}"])
return "\n".join(lines).strip()
lines = [
"You are the Little Tutor in a sidebar, answering local questions about chat content.",
"The learner's exact selection is the direct referent of the question; use the containing message only to determine what that selection means here.",
"Prioritize definitions, code, surrounding sentences, and symbol relationships in the source message. Do not reinterpret a short identifier as an unrelated abbreviation.",
"Do not read, cite, or write global memory. Never reinterpret words such as 'this', 'it', or 'the above' as referring to the memory system.",
"If an earlier answer drifted away from the selection, correct it explicitly and return to the selection.",
"Answer clearly and step by step; do not invent information absent from the source message.",
]
if source_message_text:
role_label = source_message_role or "unknown"
lines.extend(
[
"",
"[Containing message]",
f"Message role: {role_label}",
source_message_text,
"",
"[Learner's exact selection]",
selected_text,
]
)
else:
lines.extend(["", "[Selected passage]", selected_text])
lines.extend(["", f"Source session: {parent_session_id}"])
return "\n".join(lines).strip()