Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

refactor(reading): move the shared reading-tool plumbing into _tool_base

flower-moon67423aec58c1
diff --git a/deeptutor/capabilities/reading/_tool_base.py b/deeptutor/capabilities/reading/_tool_base.py
new file mode 100644
index 000000000..27bf7d7b7
--- /dev/null
+++ b/deeptutor/capabilities/reading/_tool_base.py
@@ -0,0 +1,86 @@
+"""Shared plumbing for the reading tools.
+
+Split out of :mod:`deeptutor.capabilities.reading.tools` so that module (and the
+figure tool beside it) stay under the repository's file-size limit. The names
+here are re-exported by ``tools`` unchanged, so existing importers keep working.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from deeptutor.core.tool_protocol import BaseTool, ToolResult
+from deeptutor.tools.prompting import load_prompt_hints
+
+logger = logging.getLogger(__name__)
+
+# Private, server-injected kwarg carrying the open material.
+MATERIAL_KWARG = "_material_id"
+WORKSPACE_KWARG = "_reading_workspace_id"
+BINDING_KWARG = "_reading_binding"
+
+
+class _ReadingToolBase(BaseTool):
+ """Shared plumbing: resolve the injected material and the store."""
+
+ def get_prompt_hints(self, language: str = "en"):
+ return load_prompt_hints(self.name, language=language)
+
+ @staticmethod
+ def _material_id(kwargs: dict[str, Any]) -> str:
+ binding = kwargs.get(BINDING_KWARG)
+ bound_id = binding.get("material_id") if isinstance(binding, dict) else ""
+ material_id = str(bound_id or kwargs.get(MATERIAL_KWARG) or "").strip()
+ if not material_id:
+ raise _NoMaterial()
+ from deeptutor.multi_user.learning_access import assert_learning_material
+
+ assert_learning_material(material_id)
+ return material_id
+
+ @staticmethod
+ def _store():
+ # Imported inside the call: ``reading.store`` reaches the path service,
+ # which reaches the runtime and the tool registry — importing it at
+ # module scope would close that cycle through the builtin registry.
+ from deeptutor.reading import ReadingStore
+
+ return ReadingStore()
+
+ @staticmethod
+ def _catalog():
+ from deeptutor.reading import ReadingCatalogStore
+
+ return ReadingCatalogStore()
+
+ @staticmethod
+ def _failure(message: str) -> ToolResult:
+ return ToolResult(content=message, success=False)
+
+
+class _NoMaterial(RuntimeError):
+ """Raised when the turn has no open material (should be unreachable)."""
+
+
+def _guard(func):
+ """Turn engine errors into readable tool failures instead of turn deaths."""
+
+ async def wrapper(self: _ReadingToolBase, **kwargs: Any) -> ToolResult:
+ from deeptutor.reading import ReadingError
+
+ try:
+ return await func(self, **kwargs)
+ except _NoMaterial:
+ return self._failure(
+ "No reading material is open. Ask the user to open a document in the reader."
+ )
+ except PermissionError as exc:
+ return self._failure(str(exc))
+ except ReadingError as exc:
+ return self._failure(str(exc))
+ except Exception: # pragma: no cover - defensive
+ logger.warning("reading tool %s failed", getattr(self, "name", "?"), exc_info=True)
+ return self._failure("The reader could not complete that request.")
+
+ return wrapper
\ No newline at end of file
diff --git a/deeptutor/capabilities/reading/tools.py b/deeptutor/capabilities/reading/tools.py
index d752f9a97..e7eb45177 100644
--- a/deeptutor/capabilities/reading/tools.py
+++ b/deeptutor/capabilities/reading/tools.py
@@ -34,14 +34,18 @@ event — no new stream channel, no change to the chat engine.
from __future__ import annotations
import asyncio
-import logging
from typing import Any
+from deeptutor.capabilities.reading._tool_base import (
+ BINDING_KWARG,
+ MATERIAL_KWARG,
+ WORKSPACE_KWARG,
+ _guard,
+ _NoMaterial,
+ _ReadingToolBase,
+)
from deeptutor.capabilities.reading.media_notes import render_media_note as _media_note
from deeptutor.core.tool_protocol import BaseTool, ToolDefinition, ToolParameter, ToolResult
-from deeptutor.tools.prompting import load_prompt_hints
-
-logger = logging.getLogger(__name__)
# Mounted together whenever a reading material is open on the turn. Kept here so
# the mount policy and the registration list cannot drift apart.
@@ -55,80 +59,10 @@ READING_TOOL_NAMES: tuple[str, ...] = (
"reader_annotate",
)
-# Private, server-injected kwarg carrying the open material.
-MATERIAL_KWARG = "_material_id"
-WORKSPACE_KWARG = "_reading_workspace_id"
-BINDING_KWARG = "_reading_binding"
-
_SEARCH_DEFAULT_LIMIT = 8
_SEARCH_MAX_LIMIT = 20
-class _ReadingToolBase(BaseTool):
- """Shared plumbing: resolve the injected material and the store."""
-
- def get_prompt_hints(self, language: str = "en"):
- return load_prompt_hints(self.name, language=language)
-
- @staticmethod
- def _material_id(kwargs: dict[str, Any]) -> str:
- binding = kwargs.get(BINDING_KWARG)
- bound_id = binding.get("material_id") if isinstance(binding, dict) else ""
- material_id = str(bound_id or kwargs.get(MATERIAL_KWARG) or "").strip()
- if not material_id:
- raise _NoMaterial()
- from deeptutor.multi_user.learning_access import assert_learning_material
-
- assert_learning_material(material_id)
- return material_id
-
- @staticmethod
- def _store():
- # Imported inside the call: ``reading.store`` reaches the path service,
- # which reaches the runtime and the tool registry — importing it at
- # module scope would close that cycle through the builtin registry.
- from deeptutor.reading import ReadingStore
-
- return ReadingStore()
-
- @staticmethod
- def _catalog():
- from deeptutor.reading import ReadingCatalogStore
-
- return ReadingCatalogStore()
-
- @staticmethod
- def _failure(message: str) -> ToolResult:
- return ToolResult(content=message, success=False)
-
-
-class _NoMaterial(RuntimeError):
- """Raised when the turn has no open material (should be unreachable)."""
-
-
-def _guard(func):
- """Turn engine errors into readable tool failures instead of turn deaths."""
-
- async def wrapper(self: _ReadingToolBase, **kwargs: Any) -> ToolResult:
- from deeptutor.reading import ReadingError
-
- try:
- return await func(self, **kwargs)
- except _NoMaterial:
- return self._failure(
- "No reading material is open. Ask the user to open a document in the reader."
- )
- except PermissionError as exc:
- return self._failure(str(exc))
- except ReadingError as exc:
- return self._failure(str(exc))
- except Exception: # pragma: no cover - defensive
- logger.warning("reading tool %s failed", getattr(self, "name", "?"), exc_info=True)
- return self._failure("The reader could not complete that request.")
-
- return wrapper
-
-
class ReadingListTabsTool(_ReadingToolBase):
"""Expose source identities without placing every source body in context."""