DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
perf(explore-context): read the source ahead of the per-turn question
zane-ic04598bfae04
diff --git a/deeptutor/capabilities/explore_context/explorer.py b/deeptutor/capabilities/explore_context/explorer.pyindex fa0ae1b3a..c554ebb46 100644--- a/deeptutor/capabilities/explore_context/explorer.py+++ b/deeptutor/capabilities/explore_context/explorer.py@@ -64,6 +64,14 @@ EXPLORE_SOURCE = "chat"# 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.@@ -191,15 +199,27 @@ class ContextExplorer:messages: list[dict[str, Any]] = [{"role": "system", "content": system_prompt},- {- "role": "user",- "content": 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)",- ),- },]+ 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)@@ -549,6 +569,81 @@ class ContextExplorer:except Exception: # pragma: no cover - usage accounting is best-effortlogger.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: the point is to move the bytes that would otherwise be+ re-read and re-billed on every turn into the cached prefix, and the+ investigation loads the largest source in full anyway. A source larger+ than the remaining allowance is still taken when it is the first pick,+ because dropping it would hand the model less than ``read_source``+ would have.+ """+ 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 selected and 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)+@staticmethoddef _source_index(context: UnifiedContext) -> dict[str, str]:idx = context.metadata.get("source_index")diff --git a/deeptutor/capabilities/explore_context/prompts/en/explore_context.yaml b/deeptutor/capabilities/explore_context/prompts/en/explore_context.yamlindex 7e8815654..90a43ff88 100644--- a/deeptutor/capabilities/explore_context/prompts/en/explore_context.yaml+++ b/deeptutor/capabilities/explore_context/prompts/en/explore_context.yaml@@ -64,6 +64,28 @@ loop:Begin investigating: call read_source as needed, then write your objective,thorough investigation.+ # Cache-shaped split of the same message: everything that repeats across+ # turns (mode, manifest, attached sources) comes first, and the only per-turn+ # bytes — the user's request — come last, so the repeated prefix is a prompt+ # cache hit. Falls back to the single-message user_template above when these+ # keys are absent.+ preamble_template: |+ Current mode: {mode}++ Manifest of readable sources (use read_source to load full text by id):+ {manifest}++ Full text of this turn's attached sources (already loaded for you — do not+ call read_source for these again):+ {sources}++ Begin investigating: call read_source for any further sources you need,+ then write your objective, thorough investigation.++ question_template: |+ The user's current request:+ {question}+forced_finish: |Investigation budget reached. Stop calling tools and write your objective,thorough investigation now from what you have gathered.diff --git a/deeptutor/capabilities/explore_context/prompts/zh/explore_context.yaml b/deeptutor/capabilities/explore_context/prompts/zh/explore_context.yamlindex 05bf0ff63..76e4e4ca5 100644--- a/deeptutor/capabilities/explore_context/prompts/zh/explore_context.yaml+++ b/deeptutor/capabilities/explore_context/prompts/zh/explore_context.yaml@@ -47,6 +47,26 @@ loop:现在开始调查:按需调用 read_source,然后写出你客观、详尽的调查结论。+ # 缓存友好版:把「每轮都一样」的内容(模式、清单、来源全文)放在前面,+ # 把「每轮都变」的用户请求放在最后一条消息。前缀缓存只认公共前缀,+ # 请求放在最前面会让后面所有稳定内容永远无法命中。+ # 缺少这两个键时回退到上面的 user_template 单条消息布局。+ preamble_template: |+ 当前模式:{mode}++ 可读来源清单(用 read_source 按 id 读取全文):+ {manifest}++ 本回合附带来源的全文(已为你预先读取,不必再次调用 read_source):+ {sources}++ 现在开始调查:需要时继续按需调用 read_source 追读其它来源,然后写出你客观、+ 详尽的调查结论。++ question_template: |+ 用户当前的请求:+ {question}+forced_finish: |调查预算已用尽。停止调用工具,用你已经读到的内容,立刻写出客观、详尽的调查结论。