DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""Agentic context investigator.
The investigator is a read-only pre-pass that runs *before* the answer loop's
first LLM call. Given the user's request and the manifest of the turn's
attached sources, it freely interleaves the ``read_source`` tool to load the
sources it actually needs, follows leads across them, and produces one
objective, third-person investigation the answer loop consumes as grounding.
``read_source`` lives **only** here: the answer loop no longer mounts it, so
loading attached-source full text is wholly owned by this pre-pass. The
investigation it returns is the answer loop's window into the sources — it
never streams CONTENT events, so it can never be mistaken for the turn's
user-facing answer.
Two execution paths:
* **Native tool calling** (:meth:`_run_loop`) — the agentic investigation: a
bounded loop of LLM call → ``read_source`` dispatch → repeat, until the model
stops calling tools and writes its investigation.
* **Fallback** (:meth:`_single_pass`) — for providers without native tool
calling (or when the loop fails): the original dump-the-source-text-and-brief
single pass, modelled on :class:`~deeptutor.agents.notebook.analysis_agent`.
"""
from __future__ import annotations
from contextlib import suppress
from dataclasses import dataclass, field
import logging
from typing import Any, Callable
from deeptutor.core.context import UnifiedContext
from deeptutor.core.trace import build_trace_metadata, merge_trace_metadata, new_call_id
from deeptutor.runtime.agentic import (
MAX_PARALLEL_TOOL_CALLS,
LLMClientConfig,
build_completion_kwargs,
build_openai_client,
can_use_native_tool_calling,
dispatch_tool_calls,
)
from deeptutor.runtime.agentic.messages import assistant_message, assistant_message_with_tool_calls
from deeptutor.runtime.agentic.tool_call_stream import ToolCallAccumulator
from deeptutor.runtime.registry.tool_registry import get_tool_registry
from deeptutor.runtime.stream_bus import StreamBus
from deeptutor.services.config.loader import get_capability_params
from deeptutor.services.llm import clean_thinking_tags, get_llm_config, get_token_limit_kwargs
from deeptutor.services.llm import stream as llm_stream
from deeptutor.services.llm.capabilities import threads_session_id
from deeptutor.services.session.provider_response_state import normalize_provider_response_state
logger = logging.getLogger(__name__)
# Trace identity. ``source="chat"`` keeps the pre-pass in the turn's existing
# activity lane; the dedicated stage gives it its own labelled group. The
# frontend keys its "Exploring your context…" status and "Context exploration"
# row header off ``call_kind="context_exploration"`` / ``stage`` — see
# ``web/components/chat/home/TracePanels.tsx``.
EXPLORE_STAGE = "context_exploration"
EXPLORE_SOURCE = "chat"
# Agentic-loop budget: at most this many LLM rounds; the model normally
# finishes earlier by writing its investigation without a tool call. The last
# round runs with tools disabled so it is always forced to finish.
MAX_LOOP_ROUNDS = 5
# Pre-loading attached sources into the *stable* prefix. The pre-pass starts
# from scratch every turn and reads the same bytes every time; carrying them in
# the leading message instead of behind a fresh tool call makes them part of
# the cache prefix. Set to 0 to keep the original read-through-the-tool layout.
PRELOAD_SOURCES_ENABLED = True
PRELOAD_MAX_SOURCES = 2
PRELOAD_MAX_CHARS = 120_000
def _budgets() -> dict:
"""This capability's per-stage token budgets, from agents.yaml.
Read at the call site rather than at import: a user who edits
``capabilities.explore_context`` should not have to restart the process,
and both call sites here run once per turn at most.
"""
return get_capability_params("explore_context")
# Single-pass fallback budgets. The same sources remain reachable via
# ``read_source`` in the loop path, so clipping here only bounds the fallback.
MAX_SOURCES = 12
CHARS_PER_SOURCE = 8000
TOTAL_CHARS = 48000
# Maps a manifest source-id prefix to a human kind label (en, zh).
_KIND_BY_PREFIX: dict[str, tuple[str, str]] = {
"hs-": ("Conversation transcript", "对话记录"),
"nb-": ("Notebook record", "笔记本记录"),
"bk-": ("Book excerpt", "书籍节选"),
"rd-": ("Reading excerpt", "阅读材料节选"),
"qb-": ("Question-bank entry", "题库条目"),
"at-": ("Document", "文档"),
}
@dataclass(slots=True)
class _CallResult:
text: str = ""
tool_calls: list[dict[str, Any]] = field(default_factory=list)
output_chars: int = 0
# Streamed to the trace and also kept: a thinking model's provider needs
# it echoed on the assistant turn that issued the tool calls.
reasoning_content: str = ""
# The provider's own native output items (Responses wire) and Anthropic's
# signed thinking blocks, replayed on the next request. On a Responses-wire
# provider the chat-dialect ``reasoning_content`` field is not understood
# by the request converter — a tool-round history that lost the native
# items is rejected by thinking models with "the ``reasoning_content`` in
# the thinking mode must be passed back to the API".
response_output_items: list[dict[str, Any]] = field(default_factory=list)
thinking_blocks: list[dict[str, Any]] = field(default_factory=list)
class ContextExplorer:
"""Investigate the turn's attached sources and return an objective briefing."""
def __init__(self, *, language: str, prompts: dict[str, Any]) -> None:
self.language = "zh" if str(language or "en").lower().startswith("zh") else "en"
self._prompts = prompts or {}
cfg = get_llm_config()
self._llm_config = cfg
self.model = getattr(cfg, "model", None)
self.api_key = getattr(cfg, "api_key", None)
self.base_url = getattr(cfg, "base_url", None)
self.api_version = getattr(cfg, "api_version", None)
self.binding = getattr(cfg, "binding", None) or "openai"
self.extra_headers = getattr(cfg, "extra_headers", None) or {}
self.reasoning_effort = getattr(cfg, "reasoning_effort", None)
self.registry = get_tool_registry()
self._client_config = LLMClientConfig(
binding=self.binding,
model=self.model,
api_key=self.api_key,
base_url=self.base_url,
api_version=self.api_version,
extra_headers=self.extra_headers or None,
reasoning_effort=self.reasoning_effort,
wire_api=getattr(cfg, "wire_api", None) or "auto",
api_format=getattr(cfg, "api_format", None) or "auto",
)
async def investigate(
self,
*,
context: UnifiedContext,
stream: StreamBus,
usage: Any | None = None,
) -> str:
"""Run the pre-pass and return the investigation wrapped in its header.
Returns ``""`` when there is nothing to investigate or every path
fails, so the caller can simply skip injection.
"""
source_index = self._source_index(context)
if not source_index:
return ""
# Choose before model effects; a native failure never replays through Python.
import os
if os.getenv("DEEPTUTOR_CHAT_ENGINE") == "typescript-native":
from deeptutor.runtime.ts_engine.config import compatibility_reason
tool = self.registry.get("read_source")
if not compatibility_reason(self._llm_config) and (
tool is not None and type(tool).__module__ == "deeptutor.tools.builtin"
):
return await self._investigate_native(context, stream, source_index, usage)
investigation = ""
if can_use_native_tool_calling(binding=self.binding, model=self.model):
try:
investigation = await self._run_loop(context, stream, source_index, usage)
except Exception:
logger.warning(
"context exploration loop failed; falling back to single pass",
exc_info=True,
)
investigation = ""
# Non-native providers, or a failed/empty loop, degrade to the robust
# dump-and-brief single pass so the answer loop is never left without
# grounding (it can no longer read sources itself).
if not investigation.strip():
investigation = await self._single_pass(context, stream, source_index, usage)
investigation = clean_thinking_tags(investigation, self.binding, self.model).strip()
if not investigation:
return ""
return f"{self._briefing_header()}\n\n{investigation}".strip()
async def _investigate_native(self, context, stream, sources, usage) -> str:
from .native import investigate_native
investigation = ""
if can_use_native_tool_calling(binding=self.binding, model=self.model):
try:
investigation = await investigate_native(self, context, stream, sources, usage)
except Exception:
logger.warning(
"native source investigation failed; trying read-only briefing", exc_info=True
)
if not investigation.strip():
try:
investigation = await investigate_native(
self, context, stream, sources, usage, single_pass=True
)
except Exception:
logger.warning("native source briefing failed", exc_info=True)
investigation = clean_thinking_tags(investigation, self.binding, self.model).strip()
return f"{self._briefing_header()}\n\n{investigation}" if investigation else ""
# ---- agentic loop ----------------------------------------------------
async def _run_loop(
self,
context: UnifiedContext,
stream: StreamBus,
source_index: dict[str, str],
usage: Any | None,
) -> str:
system_prompt = self._t("loop.system").format(tool_call_limit=MAX_PARALLEL_TOOL_CALLS)
user_template = self._t("loop.user_template")
if not system_prompt or not user_template:
logger.warning("explore_context loop prompts missing; using single pass")
return ""
messages: list[dict[str, Any]] = [
{"role": "system", "content": system_prompt},
]
question = (context.user_message or "").strip() or "(empty)"
mode = str(context.active_capability or "chat")
manifest = (context.source_manifest or "").strip() or "(none)"
cache_shaped = self._cache_shaped_messages(
source_index=source_index,
question=question,
mode=mode,
manifest=manifest,
)
if cache_shaped:
messages.extend(cache_shaped)
else:
messages.append(
{
"role": "user",
"content": user_template.format(
question=question, mode=mode, manifest=manifest
),
}
)
tool_schemas = self._read_source_schemas(source_index)
augmenter = self._augmenter(source_index)
client = build_openai_client(self._client_config)
call_id = new_call_id("explore-context")
stage_meta = build_trace_metadata(
call_id=call_id,
phase=EXPLORE_STAGE,
label=self._status_exploring(),
call_kind="context_exploration",
trace_id=call_id,
trace_role="explore",
trace_group="stage",
)
chunk_meta = merge_trace_metadata(stage_meta, {"trace_kind": "llm_chunk"})
investigation = ""
total_in = 0
total_out = 0
nudged_empty_finish = False
forced_finish_appended = False
async with stream.stage(EXPLORE_STAGE, source=EXPLORE_SOURCE, metadata=stage_meta):
await stream.progress(
self._status_exploring(),
source=EXPLORE_SOURCE,
stage=EXPLORE_STAGE,
metadata=merge_trace_metadata(
stage_meta, {"trace_kind": "call_status", "call_state": "running"}
),
)
for round_idx in range(MAX_LOOP_ROUNDS):
is_last = round_idx == MAX_LOOP_ROUNDS - 1
if is_last and not forced_finish_appended:
# Budget exhausted while still calling tools — force a
# tool-less finish from what has been gathered.
messages.append({"role": "user", "content": self._forced_finish_instruction()})
forced_finish_appended = True
total_in += sum(_content_chars(m) for m in messages)
result = await self._call_llm(
client,
messages,
tool_schemas if not is_last else None,
chunk_meta,
stream,
context.session_id,
)
total_out += result.output_chars
if not result.tool_calls:
investigation = result.text
if (
not investigation.strip()
and result.reasoning_content
and not is_last
and not nudged_empty_finish
):
# The round burned its output budget on internal
# reasoning and never acted — the shape a thinking
# model falls into on a tight per-round budget. Nudge
# it once with the same forced-finish instruction the
# last round uses; a second reasoning-only round still
# ends the loop and degrades to the single pass.
nudged_empty_finish = True
await stream.progress(
self._t(
"status.reasoning_only_nudged",
default=(
"The exploration round produced only internal "
"reasoning; asked the model to write its "
"investigation now."
),
),
source=EXPLORE_SOURCE,
stage=EXPLORE_STAGE,
metadata=merge_trace_metadata(stage_meta, {"trace_kind": "warning"}),
)
nudged = _assistant_message_with_provider_state(result)
messages.append(nudged)
messages.append(
{"role": "user", "content": self._forced_finish_instruction()}
)
forced_finish_appended = True
continue
break
messages.append(_assistant_message_with_provider_state(result))
dispatch = await dispatch_tool_calls(
tool_calls=result.tool_calls,
context=context,
stream=stream,
source=EXPLORE_SOURCE,
stage=EXPLORE_STAGE,
iteration_index=round_idx,
registry=self.registry,
kwarg_augmenter=augmenter,
tool_call_label=self._t("labels.tool_call", default="Tool call"),
trace_id_prefix="explore-context",
)
messages.extend(dispatch.tool_messages)
await stream.progress(
"",
source=EXPLORE_SOURCE,
stage=EXPLORE_STAGE,
metadata=merge_trace_metadata(
stage_meta, {"trace_kind": "call_status", "call_state": "complete"}
),
)
self._account_usage(usage, total_in, total_out, investigation)
return investigation
async def _call_llm(
self,
client: Any,
messages: list[dict[str, Any]],
tool_schemas: list[dict[str, Any]] | None,
chunk_meta: dict[str, Any],
stream: StreamBus,
session_id: str,
) -> _CallResult:
"""One streamed LLM call. All output streams to the *thinking* channel
(never CONTENT — that is the answer loop's channel); the returned text
is the round's investigation when it carries no tool calls."""
kwargs: dict[str, Any] = {
"model": self.model,
"messages": messages,
"stream": True,
**build_completion_kwargs(
temperature=0.2,
model=self.model,
max_tokens=_budgets()["loop"]["max_tokens"],
binding=self.binding,
reasoning_effort=self.reasoning_effort,
),
}
if threads_session_id(self.binding):
kwargs["deeptutor_session_id"] = f"{session_id}:explore"
if tool_schemas:
kwargs["tools"] = tool_schemas
kwargs["tool_choice"] = "auto"
text_parts: list[str] = []
reasoning_parts: list[str] = []
response_output_items: list[dict[str, Any]] = []
thinking_blocks: list[dict[str, Any]] = []
tool_acc = ToolCallAccumulator()
output_chars = 0
response_stream = await client.chat.completions.create(**kwargs)
try:
async for chunk in response_stream:
choices = getattr(chunk, "choices", None) or []
if not choices:
continue
choice = choices[0]
provider_fields = getattr(choice, "provider_specific_fields", None)
if isinstance(provider_fields, dict):
native_items = provider_fields.get("native_output_items")
if isinstance(native_items, list):
response_output_items.extend(
item for item in native_items if isinstance(item, dict)
)
blocks = provider_fields.get("thinking_blocks")
if isinstance(blocks, list):
thinking_blocks.extend(block for block in blocks if isinstance(block, dict))
delta = getattr(choice, "delta", None)
if delta is None:
continue
reasoning = getattr(delta, "reasoning_content", None) or getattr(
delta, "reasoning", None
)
if reasoning:
reasoning_parts.append(str(reasoning))
output_chars += len(reasoning)
await stream.thinking(
reasoning, source=EXPLORE_SOURCE, stage=EXPLORE_STAGE, metadata=chunk_meta
)
content = getattr(delta, "content", None)
if content:
output_chars += len(content)
text_parts.append(content)
await stream.thinking(
content, source=EXPLORE_SOURCE, stage=EXPLORE_STAGE, metadata=chunk_meta
)
for tc in getattr(delta, "tool_calls", None) or []:
output_chars += tool_acc.feed(tc)
finally:
close = getattr(response_stream, "close", None)
if callable(close):
with suppress(Exception):
await close()
tool_calls = tool_acc.collected()
return _CallResult(
text="".join(text_parts),
tool_calls=tool_calls,
output_chars=output_chars,
reasoning_content="".join(reasoning_parts),
response_output_items=response_output_items,
thinking_blocks=thinking_blocks,
)
def _read_source_schemas(self, source_index: dict[str, str]) -> list[dict[str, Any]]:
schemas = self.registry.build_openai_schemas(["read_source"])
source_ids = sorted(source_index.keys())
for schema in schemas:
function = schema.get("function") if isinstance(schema, dict) else None
if not isinstance(function, dict):
continue
parameters = function.get("parameters")
if not isinstance(parameters, dict):
continue
properties = parameters.get("properties") or {}
if (
function.get("name") == "read_source"
and isinstance(properties.get("source_id"), dict)
and source_ids
):
properties["source_id"]["enum"] = source_ids
parameters["additionalProperties"] = False
return schemas
@staticmethod
def _augmenter(source_index: dict[str, str]) -> Callable[..., dict[str, Any]]:
def _augment(tool_name: str, args: dict[str, Any], _ctx: UnifiedContext) -> dict[str, Any]:
kwargs = dict(args)
if tool_name == "read_source":
kwargs["source_index"] = source_index
return kwargs
return _augment
# ---- single-pass fallback -------------------------------------------
async def _single_pass(
self,
context: UnifiedContext,
stream: StreamBus,
source_index: dict[str, str],
usage: Any | None,
) -> str:
sources_text = self._render_source_blocks(source_index)
if not sources_text:
return ""
system_prompt = self._t("system")
user_template = self._t("user_template")
if not system_prompt or not user_template:
logger.warning("explore_context single-pass prompts missing; skipping pre-pass")
return ""
user_prompt = user_template.format(
question=(context.user_message or "").strip() or "(empty)",
mode=str(context.active_capability or "chat"),
manifest=(context.source_manifest or "").strip() or "(none)",
sources=sources_text,
)
call_id = new_call_id("explore-context")
stage_meta = build_trace_metadata(
call_id=call_id,
phase=EXPLORE_STAGE,
label=self._status_exploring(),
call_kind="context_exploration",
trace_id=call_id,
trace_role="explore",
trace_group="stage",
)
chunk_meta = merge_trace_metadata(stage_meta, {"trace_kind": "llm_chunk"})
chunks: list[str] = []
async with stream.stage(EXPLORE_STAGE, source=EXPLORE_SOURCE, metadata=stage_meta):
await stream.progress(
self._status_exploring(),
source=EXPLORE_SOURCE,
stage=EXPLORE_STAGE,
metadata=merge_trace_metadata(
stage_meta, {"trace_kind": "call_status", "call_state": "running"}
),
)
try:
async for chunk in llm_stream(
prompt=user_prompt,
system_prompt=system_prompt,
model=self.model,
api_key=self.api_key,
base_url=self.base_url,
api_version=self.api_version,
binding=self.binding,
temperature=0.2,
**self._token_kwargs(_budgets()["briefing"]["max_tokens"]),
):
if not chunk:
continue
chunks.append(chunk)
await stream.thinking(
chunk, source=EXPLORE_SOURCE, stage=EXPLORE_STAGE, metadata=chunk_meta
)
except Exception:
logger.warning("context exploration single pass failed", exc_info=True)
await stream.progress(
"",
source=EXPLORE_SOURCE,
stage=EXPLORE_STAGE,
metadata=merge_trace_metadata(
stage_meta, {"trace_kind": "call_status", "call_state": "complete"}
),
)
briefing = clean_thinking_tags("".join(chunks), self.binding, self.model).strip()
self._account_usage(usage, len(system_prompt) + len(user_prompt), len(briefing), briefing)
return briefing
def _render_source_blocks(self, source_index: dict[str, str]) -> str:
blocks: list[str] = []
total = 0
for sid, text in source_index.items():
body = str(text or "").strip()
if not body:
continue
if len(blocks) >= MAX_SOURCES or total >= TOTAL_CHARS:
break
remaining = TOTAL_CHARS - total
clipped = self._clip(body, min(CHARS_PER_SOURCE, remaining))
blocks.append(f"### [{sid}] ({self._kind_label(sid)})\n{clipped}")
total += len(clipped)
return "\n\n".join(blocks)
def _kind_label(self, sid: str) -> str:
for prefix, (en, zh) in _KIND_BY_PREFIX.items():
if sid.startswith(prefix):
return zh if self.language == "zh" else en
return "来源" if self.language == "zh" else "Source"
def _clip(self, text: str, limit: int) -> str:
text = (text or "").strip()
if limit <= 0:
return ""
if len(text) <= limit:
return text
note = "\n…(已截断)" if self.language == "zh" else "\n…(truncated)"
return text[:limit].rstrip() + note
# ---- shared helpers --------------------------------------------------
def _account_usage(
self, usage: Any | None, input_chars: int, output_chars: int, produced: str
) -> None:
if usage is None or not produced.strip():
return
try:
usage.add_estimated(input_chars=input_chars, output_chars=output_chars)
except Exception: # pragma: no cover - usage accounting is best-effort
logger.debug("explore_context usage accounting failed", exc_info=True)
def _cache_shaped_messages(
self,
*,
source_index: dict[str, str],
question: str,
mode: str,
manifest: str,
) -> list[dict[str, Any]]:
"""Lay the investigation out so the repeatable bytes come first.
Provider prompt caches match a *prefix*, so only the bytes before the
first per-turn difference can ever be reused. The original layout put
the user's question at the top of the first message, which meant the
longest shared prefix with the previous turn ended a few tokens in and
every byte the pre-pass re-read — including tens of thousands of tokens
of unchanged source text — was billed at the miss rate, every turn.
Here the question is the *last* message and everything ahead of it
(mode, manifest, attached sources) is byte-stable for as long as the
attachments are, so it becomes a cache hit.
Returns ``[]`` when the localized split prompts are absent, leaving the
caller on the original single-message layout.
"""
preamble_template = self._t("loop.preamble_template")
question_template = self._t("loop.question_template")
if not preamble_template or not question_template:
return []
selected = self._preload_selection(source_index)
sources_text = self._render_preloaded_sources(source_index, selected)
return [
{
"role": "user",
"content": preamble_template.format(
mode=mode, manifest=manifest, sources=sources_text or "(none)"
),
},
{"role": "user", "content": question_template.format(question=question)},
]
def _preload_selection(self, source_index: dict[str, str]) -> list[str]:
"""Which attached sources to carry in the stable prefix.
Longest first within the hard preload allowance. Oversized sources
remain available through read_source without overflowing every request.
"""
if not PRELOAD_SOURCES_ENABLED or PRELOAD_MAX_SOURCES <= 0:
return []
ranked = sorted(
(sid for sid, body in source_index.items() if str(body or "").strip()),
key=lambda sid: (-len(str(source_index.get(sid) or "")), sid),
)
selected: list[str] = []
total = 0
for sid in ranked:
if len(selected) >= PRELOAD_MAX_SOURCES:
break
size = len(str(source_index.get(sid) or ""))
if total + size > PRELOAD_MAX_CHARS:
continue
selected.append(sid)
total += size
return selected
def _render_preloaded_sources(self, source_index: dict[str, str], selected: list[str]) -> str:
blocks: list[str] = []
for sid in selected:
body = str(source_index.get(sid) or "").strip()
if body:
blocks.append(f"### [{sid}] ({self._kind_label(sid)})\n{body}")
return "\n\n".join(blocks)
@staticmethod
def _source_index(context: UnifiedContext) -> dict[str, str]:
idx = context.metadata.get("source_index")
if isinstance(idx, dict) and idx:
return {str(k): str(v) for k, v in idx.items()}
return {}
def _token_kwargs(self, max_tokens: int) -> dict[str, Any]:
if not self.model:
return {}
return get_token_limit_kwargs(self.model, max_tokens)
def _t(self, key: str, default: str = "") -> str:
value: Any = self._prompts
for part in key.split("."):
if not isinstance(value, dict) or part not in value:
return default
value = value[part]
return value.strip() if isinstance(value, str) else default
def _forced_finish_instruction(self) -> str:
return self._t(
"loop.forced_finish",
default=(
"Investigation budget reached. Stop calling tools and write your "
"objective, detailed investigation now from what you have gathered."
),
)
def _status_exploring(self) -> str:
return self._t(
"status.exploring",
default="上下文调查" if self.language == "zh" else "Context exploration",
)
def _briefing_header(self) -> str:
return self._t("briefing_header", default="[Context Investigation]")
def _assistant_message_with_provider_state(result: _CallResult) -> dict[str, Any]:
"""The round's assistant turn with its reasoning replay state attached.
The chat-dialect ``reasoning_content`` field covers Chat Completions
providers. On a Responses-wire provider the request converter only
replays reasoning from the provider's own native output items — a history
that lost them is rejected by thinking models with "the
``reasoning_content`` in the thinking mode must be passed back to the
API" (#1400), so the native items ride along as private state.
"""
if result.tool_calls:
message = assistant_message_with_tool_calls(
result.text,
result.tool_calls,
reasoning_content=result.reasoning_content or None,
thinking_blocks=result.thinking_blocks or None,
)
else:
message = assistant_message(
result.text,
reasoning_content=result.reasoning_content or None,
thinking_blocks=result.thinking_blocks or None,
)
state: dict[str, Any] = {}
if result.response_output_items:
state["responses_output_items"] = result.response_output_items
if result.reasoning_content:
state["reasoning_content"] = result.reasoning_content
if result.thinking_blocks:
state["thinking_blocks"] = result.thinking_blocks
normalized = normalize_provider_response_state(state)
if normalized is not None:
message["_provider_response_state"] = normalized
return message
def _content_chars(message: dict[str, Any]) -> int:
content = message.get("content")
if isinstance(content, str):
return len(content)
if isinstance(content, list):
return sum(len(str(part.get("text") or "")) for part in content if isinstance(part, dict))
return 0
__all__ = ["ContextExplorer", "EXPLORE_STAGE"]