DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
feat: modularize installation and enforce feature dependency boundaries
Bingxi Zhao (Frank)fbab59acbf2e
diff --git a/.github/workflows/modules.yml b/.github/workflows/modules.ymlnew file mode 100644index 000000000..3cbe86e48--- /dev/null+++ b/.github/workflows/modules.yml@@ -0,0 +1,28 @@+name: Modular installation+on:+ pull_request:+ paths:+ - 'deeptutor/**'+ - 'deeptutor_cli/**'+ - 'pyproject.toml'+ - 'build_support.py'+ - 'setup.py'+ - 'scripts/*module*'+ - 'scripts/check_minimal_install.py'+ - '.github/workflows/modules.yml'+ workflow_dispatch:+jobs:+ wheel-lifecycle:+ runs-on: ubuntu-latest+ strategy:+ matrix:+ python: ['3.11', '3.13']+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-python@v5+ with:+ python-version: ${{ matrix.python }}+ - run: python -m pip install --upgrade pip setuptools wheel+ - run: python scripts/sync_module_requirements.py --check+ - run: python scripts/build_modules.py --output dist/modules --module core --module solve --module parsing --module research --module calendar+ - run: python scripts/check_module_install.py --wheelhouse dist/modules --extendeddiff --git a/.github/workflows/pypi-release.yml b/.github/workflows/pypi-release.ymlindex 389855de5..30ce51470 100644--- a/.github/workflows/pypi-release.yml+++ b/.github/workflows/pypi-release.yml@@ -1,11 +1,9 @@name: PyPI Release# Triggered when a GitHub Release is published.-# Publishes the full app package with the version derived from the release tag:-# - deeptutor (Python backend/CLI + packaged Next.js standalone assets)-#-# The CLI-only package is intentionally not published to PyPI; install it from-# a local checkout with `python -m pip install -e ./packaging/deeptutor-cli`.+# Builds disjoint core, feature, server and Web wheels from one revision.+# Each distribution needs this workflow configured as its trusted publisher.+# The CLI compatibility distribution contains metadata only.## Expected tag format: vMAJOR.MINOR.PATCH, with PEP 440-compatible suffixes allowed.# Example: GitHub release tag v1.3.10 -> PyPI version 1.3.10.@@ -95,7 +93,7 @@ jobs:- name: Install build toolsrun: |python -m pip install --upgrade pip- python -m pip install --upgrade build packaging twine+ python -m pip install --upgrade build packaging twine setuptools wheel- name: Verify release tag matches deeptutor/__version__.pyid: version@@ -148,12 +146,7 @@ jobs:run: |set -euo pipefailmkdir -p dist/deeptutor- # Run from /tmp so any repository-local build/ directory cannot shadow- # PyPA's `build` module during repeated package builds.- # Wheels are the supported public install artifacts. The full app- # wheel contains packaged Next.js assets; source distributions would- # either duplicate those large assets or require a frontend build.- (cd /tmp && python -m build --wheel --outdir "$GITHUB_WORKSPACE/dist/deeptutor" "$GITHUB_WORKSPACE")+ python scripts/build_modules.py --output dist/deeptutor- name: Verify package metadatarun: |@@ -175,7 +168,7 @@ jobs:raise SystemExit(f"Missing expected distributions: {missing}")PY- - name: Publish deeptutor to PyPI+ - name: Publish module distributions to PyPIuses: pypa/gh-action-pypi-publish@release/v1with:packages-dir: dist/deeptutor/diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.ymlindex f7b3ea587..2e7fea507 100644--- a/.github/workflows/tests.yml+++ b/.github/workflows/tests.yml@@ -54,7 +54,7 @@ jobs:with:python-version: "3.11"- name: Install compatibility adapters- run: pip install -r requirements/server.txt -r requirements/partners.txt pytest pytest-asyncio+ run: pip install -r requirements/full.txt -r requirements/partners.txt pytest pytest-asyncio- name: Create synthetic model configurationrun: |mkdir -p data/user/settings@@ -238,14 +238,14 @@ jobs:uses: actions/cache@v4with:path: ~/.cache/pip- key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('requirements/server.txt', 'requirements/cli.txt') }}+ key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('requirements/full.txt', 'requirements/cli.txt') }}restore-keys: |${{ runner.os }}-pip-${{ matrix.python-version }}-- name: Install minimal dependencies for import checkrun: |python -m pip install --upgrade pip- pip install -r requirements/server.txt+ pip install -r requirements/full.txt# Exercise project metadata too, especially `requires-python`.pip install -e . --no-deps@@ -310,14 +310,14 @@ jobs:uses: actions/cache@v4with:path: ~/.cache/pip- key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('requirements/server.txt', 'requirements/cli.txt', 'requirements/partners.txt', 'pyproject.toml') }}+ key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('requirements/full.txt', 'requirements/cli.txt', 'requirements/partners.txt', 'pyproject.toml') }}restore-keys: |${{ runner.os }}-pip-${{ matrix.python-version }}-- name: Install smoke test dependenciesrun: |python -m pip install --upgrade pip- pip install -r requirements/server.txt+ pip install -r requirements/full.txtpip install -r requirements/partners.txtpip install pytest pytest-asyncio@@ -367,7 +367,7 @@ jobs:with:python-version: "3.11"- name: Install test dependencies- run: pip install -r requirements/server.txt pytest pytest-asyncio+ run: pip install -r requirements/full.txt pytest pytest-asyncio- name: Check real rendering, isolation, cancellation and timeoutenv:DEEPTUTOR_TEST_VIDEO_SANDBOX: "1"diff --git a/.gitignore b/.gitignoreindex b1ee47df4..2bffb78d3 100644--- a/.gitignore+++ b/.gitignore@@ -38,6 +38,9 @@ __pycache__/*.so# Distribution/Packaging+# Generated by prepare_web_package.py; the source wrapper remains tracked.+/deeptutor_web/*+!/deeptutor_web/__init__.py.Pythonbuild/develop-eggs/diff --git a/MANIFEST.in b/MANIFEST.inindex 67dfdd4c4..c0e1e8c51 100644--- a/MANIFEST.in+++ b/MANIFEST.in@@ -1,2 +1,8 @@recursive-include deeptutor_web *recursive-include deeptutor_web/.next *++include build_support.py setup.py+recursive-include deeptutor *.py *.json *.yaml *.yml *.md *.ts *.tsx *.js *.mjs *.sh *.j2+recursive-include deeptutor_cli *.py *.json *.yaml+include scripts/build_modules.py scripts/check_minimal_install.py scripts/check_module_install.py scripts/sync_module_requirements.py+recursive-include packaging *.tomldiff --git a/README.md b/README.mdindex cfa7e10d5..7e21cf86c 100644--- a/README.md+++ b/README.md@@ -324,11 +324,11 @@ shown as **best effort** in Workspace settings.<details><summary><b>Option 1 — Install From PyPI</b> · full local Web app + CLI, no clone required</summary>-Full local Web app + CLI, no clone required. Needs **Python 3.11–3.14** and a **Node.js 20+** runtime on PATH (the packaged Next.js standalone server is spawned by `deeptutor start`).+Use `deeptutor[full]` for the Web app and CLI, or `deeptutor` for core chat. Needs **Python 3.11–3.14** and a **Node.js 20+** runtime on PATH (the packaged Next.js standalone server is spawned by `deeptutor start`).```bashmkdir -p my-deeptutor && cd my-deeptutor-pip install -U deeptutor+pip install -U "deeptutor[full]"deeptutor init # prompts for ports + LLM provider + optional embedding/searchdeeptutor start # starts backend + frontend; keep the terminal open```@@ -356,7 +356,8 @@ python3 -m venv .venv && source .venv/bin/activatepython -m pip install --upgrade pip# Install backend + frontend deps-python -m pip install -e .+python -m pip install -r requirements/full.txt+python -m pip install -e . --no-deps( cd web && npm ci --legacy-peer-deps )deeptutor init@@ -384,7 +385,7 @@ pip install -e ".[rag-lightrag]" # Built-in LightRAG engine (exact supportedpip install -e ".[graphrag]" # Microsoft GraphRAG engine (Python 3.11–3.13)pip install -e ".[dev]" # tests/lint toolspip install -e ".[partners]" # Partner IM channel SDKs-pip install -e ".[video-learning]" # compatibility extra; captions ship in the full/CLI installs+pip install -e ".[video-learning]" # captions for reading/video-learningpip install -e ".[matrix]" # Matrix channel without E2EE/libolmpip install -e ".[matrix-e2e]" # Matrix E2EE; requires libolmpip install -e ".[math-animator]" # Manim addon; requires LaTeX/ffmpeg/system libs@@ -512,7 +513,7 @@ Docker Desktop (macOS/Windows) usually resolves `host.docker.internal` without `<details><summary><b>Option 4 — CLI Only</b> · no Web UI, from a source checkout</summary>-When you don't need the Web UI. The CLI-only package is installed from a source checkout, not from PyPI.+When you do not need the Web UI, install the core from this checkout. Add feature modules separately as needed.```bashgit clone https://github.com/HKUDS/DeepTutor.git@@ -523,7 +524,7 @@ cd DeepTutorpython3 -m venv .venv-cli && source .venv-cli/bin/activatepython -m pip install --upgrade pip-python -m pip install -e ./packaging/deeptutor-cli+python -m pip install -e .deeptutor init --clideeptutor chat```@@ -1045,13 +1046,13 @@ Copilot-specific Responses compatibility is applied at dispatch without rewritin<details><summary><b>CLI-only distribution</b></summary>-The CLI-only package lives in `packaging/deeptutor-cli`. In this checkout, install it from source:+The core supplies CLI and SDK; `deeptutor-cli` is a compatibility metapackage. Install core from this checkout:```bash-python -m pip install -e ./packaging/deeptutor-cli+python -m pip install -e .```-It isn't published to PyPI yet, so the main [Get Started](#-get-started) section keeps the source-install path.+Use `deeptutor module list` to inspect optional modules; install or remove them with the environment stopped. See [module installation](docs-for-dev/MODULES.md).</details>diff --git a/build_support.py b/build_support.pynew file mode 100644index 000000000..18dca5de9--- /dev/null+++ b/build_support.py@@ -0,0 +1,49 @@+"""Setuptools filter: the root wheel owns only core files.++The source distribution retains all sources so the module wheel builder can+produce the complete family from the same revision.+"""++from functools import cache+import json+from pathlib import Path++from setuptools.command.build_py import build_py++ROOT = Path(__file__).resolve().parent+++@cache+def ownership_prefixes():+ return tuple(+ (prefix, module["id"])+ for path in (ROOT / "deeptutor/modules/manifests").glob("*.json")+ for module in [json.loads(path.read_text(encoding="utf-8"))]+ for prefix in module["paths"]+ )+++@cache+def owner(relative: str) -> str:+ candidates = [+ (len(prefix), name)+ for prefix, name in ownership_prefixes()+ if relative == prefix or relative.startswith(prefix + "/")+ ]+ return max(candidates)[1] if candidates else "core"+++class CoreBuildPy(build_py):+ def find_package_modules(self, package, package_dir):+ return [+ row+ for row in super().find_package_modules(package, package_dir)+ if owner(Path(row[2]).resolve().relative_to(ROOT).as_posix()) == "core"+ ]++ def find_data_files(self, package, src_dir):+ return [+ path+ for path in super().find_data_files(package, src_dir)+ if owner(Path(path).resolve().relative_to(ROOT).as_posix()) == "core"+ ]diff --git a/deeptutor/agents/_shared/tool_composition.py b/deeptutor/agents/_shared/tool_composition.pyindex c64fa9241..a6b1f4904 100644--- a/deeptutor/agents/_shared/tool_composition.py+++ b/deeptutor/agents/_shared/tool_composition.py@@ -25,6 +25,7 @@ from dataclasses import dataclassimport jsonfrom typing import Any+from deeptutor.modules.catalog import module_enabledfrom deeptutor.tools.builtin import (BUILTIN_TOOL_NAMES,CONFIGURABLE_BUILTIN_TOOL_NAMES,@@ -307,6 +308,8 @@ def user_has_memory() -> bool:a tool with no payload to read."""try:+ if not module_enabled("memory"):+ return Falsefrom deeptutor.services.memory import get_memory_storestore = get_memory_store()@@ -325,6 +328,8 @@ def user_has_notebooks() -> bool:fail-closed posture as :func:`user_has_memory`."""try:+ if not module_enabled("notebook"):+ return Falsefrom deeptutor.services.notebook import get_notebook_managernotebooks = get_notebook_manager().list_notebooks()@@ -344,6 +349,8 @@ def user_has_mastery_topics() -> bool:``LearningStore.default_db_path``)."""try:+ if not module_enabled("mastery"):+ return Falsefrom deeptutor.learning.navigation import learner_has_topicsreturn learner_has_topics()diff --git a/deeptutor/agents/chat/capability.py b/deeptutor/agents/chat/capability.pyindex 5cea4ce84..0dc6a9b5a 100644--- a/deeptutor/agents/chat/capability.py+++ b/deeptutor/agents/chat/capability.py@@ -2,25 +2,15 @@from __future__ import annotations-from deeptutor.agents.chat.agentic_pipeline import CHAT_OPTIONAL_TOOLS, AgenticChatPipeline-from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability+from deeptutor.agents.chat.agentic_pipeline import AgenticChatPipeline+from deeptutor.core.capability_protocol import TurnCapabilityfrom deeptutor.core.context import UnifiedContext-from deeptutor.runtime.request_contracts import get_capability_request_schema+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifestfrom deeptutor.runtime.stream_bus import StreamBusclass ChatCapability(TurnCapability):- manifest = CapabilityManifest(- name="chat",- description=(- "Agentic chat: an exploring agent loop with tools, followed by "- "a respond stage that streams the answer."- ),- stages=["exploring", "responding"],- tools_used=CHAT_OPTIONAL_TOOLS,- cli_aliases=["chat"],- request_schema=get_capability_request_schema("chat"),- )+ manifest = builtin_capability_manifest("chat")async def run(self, context: UnifiedContext, stream: StreamBus) -> None:pipeline = AgenticChatPipeline(language=context.language)diff --git a/deeptutor/agents/loop/pipeline.py b/deeptutor/agents/loop/pipeline.pyindex 01474c145..cc5579d91 100644--- a/deeptutor/agents/loop/pipeline.py+++ b/deeptutor/agents/loop/pipeline.py@@ -697,6 +697,8 @@ class AgenticLoopPipeline:)async def _pageindex_sdk_tool_bundles(self, context: UnifiedContext):+ if not self._selected_kbs(context):+ return []from deeptutor.multi_user.knowledge_access import resolve_kbfrom deeptutor.services.rag.factory import PAGEINDEX_OSS_PROVIDER, PAGEINDEX_PROVIDERfrom deeptutor.services.rag.pipelines.pageindex.tools import build_sdk_tool_bundle@@ -766,16 +768,22 @@ class AgenticLoopPipeline:def _compose_enabled_tools(self, context: UnifiedContext) -> list[str]:is_partner = self._is_partner_turn(context)- from deeptutor.tools.research_tools import scientific_context+ from deeptutor.modules.catalog import module_enabled++ scientific = False+ if module_enabled("research"):+ from deeptutor.tools.research_tools import scientific_context++ scientific = scientific_context(+ context.user_message, context.active_capability, context.enabled_tools or []+ )composed = compose_enabled_tools(registry=self.tool_lookup,requested_tools=context.enabled_tools,optional_whitelist=LOOP_OPTIONAL_TOOLS,mount_flags=ToolMountFlags(- has_scientific_research=scientific_context(- context.user_message, context.active_capability, context.enabled_tools or []- ),+ has_scientific_research=scientific,# PageIndex KBs are read via the preloaded MCP tools, not rag —# a conversation with only PageIndex KBs doesn't mount rag at all.# Excludes KBs owned by an exclusive capability (an Obsidian vault@@ -1837,6 +1845,8 @@ class AgenticLoopPipeline:def _rag_kbs(self, context: UnifiedContext) -> list[str]:"""Attached KBs served by rag; PageIndex KBs use their SDK tools."""+ if not self._selected_kbs(context):+ return []from deeptutor.services.rag.pipelines.pageindex import is_pageindex_kbreturn [kb for kb in self._selected_kbs(context) if not is_pageindex_kb(kb)]diff --git a/deeptutor/agents/math_animator/capability.py b/deeptutor/agents/math_animator/capability.pyindex 6883acb6a..98508ac1e 100644--- a/deeptutor/agents/math_animator/capability.py+++ b/deeptutor/agents/math_animator/capability.py@@ -7,36 +7,17 @@ import timefrom typing import Anyfrom deeptutor.agents._shared.capability_result import emit_capability_result-from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability+from deeptutor.core.capability_protocol import TurnCapabilityfrom deeptutor.core.context import UnifiedContextfrom deeptutor.core.trace import build_trace_metadata, merge_trace_metadata, new_call_idfrom deeptutor.i18n import StatusI18nfrom deeptutor.runtime.agentic.usage import UsageTracker-from deeptutor.runtime.request_contracts import get_capability_request_schema+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifestfrom deeptutor.runtime.stream_bus import StreamBusclass MathAnimatorCapability(TurnCapability):- manifest = CapabilityManifest(- name="math_animator",- description="Generate math animations or storyboard images with Manim.",- stages=[- "concept_analysis",- "concept_design",- "code_generation",- "code_retry",- "summary",- "render_output",- ],- tools_used=[],- cli_aliases=["animate"],- request_schema=get_capability_request_schema("math_animator"),- config_defaults={- "output_mode": "video",- "quality": "medium",- "style_hint": "",- },- )+ manifest = builtin_capability_manifest("math_animator")async def run(self, context: UnifiedContext, stream: StreamBus) -> None:if importlib.util.find_spec("manim") is None:diff --git a/deeptutor/agents/math_animator/renderer.py b/deeptutor/agents/math_animator/renderer.pyindex f5702e638..6e53dd3ac 100644--- a/deeptutor/agents/math_animator/renderer.py+++ b/deeptutor/agents/math_animator/renderer.py@@ -3,6 +3,7 @@from __future__ import annotationsimport asyncio+import osfrom pathlib import Pathimport reimport subprocess@@ -171,6 +172,7 @@ class ManimRenderService:command,stdout=subprocess.PIPE,stderr=subprocess.PIPE,+ start_new_session=os.name != "nt",)_SENTINEL = None@@ -191,16 +193,26 @@ class ManimRenderService:stdout_lines: list[str] = []stderr_lines: list[str] = []streams_open = 2- while streams_open > 0:- item = await queue.get()- if item is _SENTINEL:- streams_open -= 1- continue- prefix, line = item- (stdout_lines if prefix == "stdout" else stderr_lines).append(line)- await self._emit_progress(f"[{prefix}] {line}", raw=True)+ try:+ async with asyncio.timeout(300):+ while streams_open > 0:+ item = await queue.get()+ if item is _SENTINEL:+ streams_open -= 1+ continue+ prefix, line = item+ lines = stdout_lines if prefix == "stdout" else stderr_lines+ lines.append(line[:4000])+ if len(lines) > 2000:+ del lines[:1000]+ await self._emit_progress(f"[{prefix}] {line[:4000]}", raw=True)+ return_code = await asyncio.to_thread(process.wait)+ except BaseException:+ from deeptutor.runtime.process import kill_process_tree- return_code = process.wait()+ await asyncio.to_thread(kill_process_tree, process.pid)+ await asyncio.to_thread(process.wait)+ raiseawait self._emit_progress(f"Manim process finished with exit code {return_code}.", raw=True)if return_code != 0:detail = trim_error_message(diff --git a/deeptutor/agents/question/capability.py b/deeptutor/agents/question/capability.pyindex 3687ec16f..c48c4f174 100644--- a/deeptutor/agents/question/capability.py+++ b/deeptutor/agents/question/capability.py@@ -17,24 +17,17 @@ import tempfilefrom typing import Anyfrom deeptutor.agents._shared.capability_result import emit_capability_result-from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability+from deeptutor.core.capability_protocol import TurnCapabilityfrom deeptutor.core.context import UnifiedContextfrom deeptutor.core.trace import merge_trace_metadatafrom deeptutor.i18n import StatusI18nfrom deeptutor.runtime.agentic.usage import UsageTracker-from deeptutor.runtime.request_contracts import get_capability_request_schema+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifestfrom deeptutor.runtime.stream_bus import StreamBusclass DeepQuestionCapability(TurnCapability):- manifest = CapabilityManifest(- name="deep_question",- description="Fast question generation (Template batches -> Generate).",- stages=["ideation", "generation"],- tools_used=["rag", "web_search", "exec"],- cli_aliases=["quiz"],- request_schema=get_capability_request_schema("deep_question"),- )+ manifest = builtin_capability_manifest("deep_question")async def run(self, context: UnifiedContext, stream: StreamBus) -> None:from deeptutor.services.llm.config import get_llm_configdiff --git a/deeptutor/agents/question/pipeline.py b/deeptutor/agents/question/pipeline.pyindex c31d61b65..bc8bc363b 100644--- a/deeptutor/agents/question/pipeline.py+++ b/deeptutor/agents/question/pipeline.py@@ -1578,6 +1578,12 @@ class QuestionPipeline:# Tool integration (mirrors chat's policy)# ------------------------------------------------------------------async def _prepare_pageindex_tools(self) -> None:+ from deeptutor.modules.catalog import require_module++ self._pageindex_tool_context = None+ if not self.kb_name:+ return+ require_module("knowledge")from deeptutor.services.rag.pipelines.pageindex.tools import (build_pageindex_tool_context,)diff --git a/deeptutor/agents/research/capability.py b/deeptutor/agents/research/capability.pyindex 1b179e84a..62d555675 100644--- a/deeptutor/agents/research/capability.py+++ b/deeptutor/agents/research/capability.py@@ -27,30 +27,15 @@ from deeptutor.agents.research.request_config import (build_research_runtime_config,validate_research_request_config,)-from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability+from deeptutor.core.capability_protocol import TurnCapabilityfrom deeptutor.core.context import UnifiedContext-from deeptutor.runtime.request_contracts import get_capability_request_schema+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifestfrom deeptutor.runtime.stream_bus import StreamBusfrom deeptutor.services.config import load_config_with_mainclass DeepResearchCapability(TurnCapability):- manifest = CapabilityManifest(- name="deep_research",- description="Agentic-loop deep research with iterative report generation.",- stages=["rephrasing", "decomposing", "researching", "reporting"],- tools_used=[- "rag",- "web_search",- "paper_search",- "preprint",- "research_audit",- "research_lit",- "exec",- ],- cli_aliases=["research"],- request_schema=get_capability_request_schema("deep_research"),- )+ manifest = builtin_capability_manifest("deep_research")async def run(self, context: UnifiedContext, stream: StreamBus) -> None:kb_name = context.knowledge_bases[0] if context.knowledge_bases else Nonediff --git a/deeptutor/agents/research/pipeline.py b/deeptutor/agents/research/pipeline.pyindex 394b041da..854a80b06 100644--- a/deeptutor/agents/research/pipeline.py+++ b/deeptutor/agents/research/pipeline.py@@ -2065,6 +2065,12 @@ class ResearchPipeline:# Tool composition for the block loop# ------------------------------------------------------------------async def _prepare_pageindex_tools(self) -> None:+ from deeptutor.modules.catalog import require_module++ self._pageindex_tool_context = None+ if not self.kb_name:+ return+ require_module("knowledge")from deeptutor.services.rag.pipelines.pageindex.tools import (build_pageindex_tool_context,)diff --git a/deeptutor/agents/video_lesson/capability.py b/deeptutor/agents/video_lesson/capability.pyindex dacc56e05..9215cb229 100644--- a/deeptutor/agents/video_lesson/capability.py+++ b/deeptutor/agents/video_lesson/capability.py@@ -7,27 +7,19 @@ import timefrom typing import Anyfrom deeptutor.agents._shared.capability_result import emit_capability_result-from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability+from deeptutor.core.capability_protocol import TurnCapabilityfrom deeptutor.core.context import UnifiedContextfrom deeptutor.core.trace import merge_trace_metadatafrom deeptutor.i18n import StatusI18nfrom deeptutor.runtime.agentic.usage import UsageTracker-from deeptutor.runtime.request_contracts import get_capability_request_schema+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifestfrom deeptutor.runtime.stream_bus import StreamBusMAX_ATTEMPTS = 3class VideoLessonCapability(TurnCapability):- manifest = CapabilityManifest(- name="video_lesson",- description="Generate an animated video lesson (Remotion) that plays in the browser.",- stages=["code_generation", "render_check", "render_output"],- tools_used=[],- cli_aliases=["lesson"],- request_schema=get_capability_request_schema("video_lesson"),- config_defaults={},- )+ manifest = builtin_capability_manifest("video_lesson")async def run(self, context: UnifiedContext, stream: StreamBus) -> None:from deeptutor.agents.video_lesson.lesson_writer import LessonWriterAgentdiff --git a/deeptutor/agents/visualize/capability.py b/deeptutor/agents/visualize/capability.pyindex 32b247740..3f2c159ab 100644--- a/deeptutor/agents/visualize/capability.py+++ b/deeptutor/agents/visualize/capability.py@@ -7,14 +7,14 @@ import loggingfrom typing import Anyfrom deeptutor.agents._shared.capability_result import emit_capability_result-from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability+from deeptutor.core.capability_protocol import TurnCapabilityfrom deeptutor.core.context import UnifiedContextfrom deeptutor.core.trace import merge_trace_metadatafrom deeptutor.i18n import StatusI18nfrom deeptutor.runtime.agentic.usage import UsageTracker+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifestfrom deeptutor.runtime.request_contracts import (VisualizeRequestConfig,- get_capability_request_schema,validate_visualize_request_config,)from deeptutor.runtime.stream_bus import StreamBus@@ -87,17 +87,7 @@ _VISUALIZE_SAFE_BUILTINS = (class VisualizeCapability(TurnCapability):- manifest = CapabilityManifest(- name="visualize",- description=(- "Generate a validated visualization with any installed visualizer "- "type, or render a Manim animation/storyboard artifact."- ),- stages=_VISUALIZE_STAGES,- tools_used=["submit_visualization"],- cli_aliases=["visualize", "viz"],- request_schema=get_capability_request_schema("visualize"),- )+ manifest = builtin_capability_manifest("visualize")async def run(self, context: UnifiedContext, stream: StreamBus) -> None:request_config = validate_visualize_request_config(context.config_overrides)@@ -286,6 +276,9 @@ class VisualizeCapability(TurnCapability):import importlib.utilimport time+ from deeptutor.modules.catalog import require_module++ require_module("renderer-manim")if importlib.util.find_spec("manim") is None:raise RuntimeError("Manim rendering requires optional dependencies. "diff --git a/deeptutor/api/main.py b/deeptutor/api/main.pyindex 27446f237..d167f447c 100644--- a/deeptutor/api/main.py+++ b/deeptutor/api/main.py@@ -3,12 +3,13 @@ from contextlib import asynccontextmanagerimport loggingimport sys-from fastapi import Depends, FastAPI, Request+from fastapi import FastAPI, Requestfrom fastapi.middleware.cors import CORSMiddlewarefrom fastapi.responses import JSONResponse, RedirectResponsefrom deeptutor.api.security_guard import install_security_guardfrom deeptutor.logging import configure_logging+from deeptutor.modules.catalog import module_enabledfrom deeptutor.services.config import (ensure_runtime_settings_files,export_runtime_settings_to_env,@@ -54,7 +55,9 @@ def validate_tool_consistency():capability_registry = get_capability_registry()tool_registry = get_tool_registry()- available_tools = set(tool_registry.list_tools())+ from deeptutor.tools.builtin_specs import BUILTIN_TOOL_NAMES++ available_tools = set(tool_registry.list_tools()) | set(BUILTIN_TOOL_NAMES)referenced_tools = set()for manifest in capability_registry.get_manifests():@@ -125,14 +128,15 @@ async def lifespan(app: FastAPI):application_container = get_application_container()app.state.application_container = application_containerawait application_container.start()- from deeptutor.api.utils.progress_broadcaster import ProgressBroadcaster- from deeptutor.api.utils.task_log_stream import get_task_stream_manager- from deeptutor.knowledge.progress_events import install_progress_ports-- install_progress_ports(- broadcast=ProgressBroadcaster.get_instance().broadcast,- emit_task_event=get_task_stream_manager().emit,- )+ if module_enabled("knowledge"):+ from deeptutor.api.utils.progress_broadcaster import ProgressBroadcaster+ from deeptutor.api.utils.task_log_stream import get_task_stream_manager+ from deeptutor.knowledge.progress_events import install_progress_ports++ install_progress_ports(+ broadcast=ProgressBroadcaster.get_instance().broadcast,+ emit_task_event=get_task_stream_manager().emit,+ )migration_reports = await application_container.run_startup_data_migrations()legacy_reports = migration_reports["legacy_chat"]migrated_reports = [report for report in legacy_reports if report.get("source_hash")]@@ -154,11 +158,12 @@ async def lifespan(app: FastAPI):)try:- from deeptutor.learning.assessment import reconcile_linked_assessments+ if module_enabled("mastery"):+ from deeptutor.learning.assessment import reconcile_linked_assessments- recovered, failed = await reconcile_linked_assessments()- if recovered or failed:- logger.info("Linked assessment recovery: recovered=%s failed=%s", recovered, failed)+ recovered, failed = await reconcile_linked_assessments()+ if recovered or failed:+ logger.info("Linked assessment recovery: recovered=%s failed=%s", recovered, failed)except Exception:logger.exception("Failed to reconcile linked assessments at startup")@@ -181,62 +186,22 @@ async def lifespan(app: FastAPI):except Exception as e:logger.warning(f"Failed to start EventBus: {e}")- async def _start_partners() -> None:- from deeptutor.services.partners import get_partner_manager-- manager = get_partner_manager()- manager.configure_runtime_owner(application_container.worker_id)- await manager.auto_start_partners()-- async def _stop_partners() -> None:- from deeptutor.services.partners import get_partner_manager-- await get_partner_manager().stop_all(preserve_auto_start=True)-- async def _start_cron() -> None:- from deeptutor.services.cron import get_cron_service-- await get_cron_service().start()-- async def _stop_cron() -> None:- from deeptutor.services.cron import get_cron_service-- await get_cron_service().stop()-- async def _start_github_sync() -> None:- from deeptutor.services.github_source.sync_service import get_sync_service-- await get_sync_service().start()-- async def _stop_github_sync() -> None:- from deeptutor.services.github_source.sync_service import get_sync_service-- await get_sync_service().stop()-- async def _start_web_source_sync() -> None:- from deeptutor.services.web_source.scheduler import (- start_web_source_sync_scheduler,- )-- await start_web_source_sync_scheduler()-- async def _stop_web_source_sync() -> None:- from deeptutor.services.web_source.scheduler import (- stop_web_source_sync_scheduler,- )-- await stop_web_source_sync_scheduler()-from deeptutor.runtime.coordination import BackgroundCommandKindasync def _handle_background_command(command) -> None:kind = str(command.kind)if kind == BackgroundCommandKind.CRON_RELOAD:+ from deeptutor.modules.catalog import require_module++ require_module("calendar")from deeptutor.services.cron import get_cron_serviceget_cron_service().reload()return+ from deeptutor.modules.catalog import require_module++ require_module("partners")from deeptutor.services.partners import get_partner_managermanager = get_partner_manager()@@ -268,42 +233,34 @@ async def lifespan(app: FastAPI):cron_service = Nonetry:- from deeptutor.services.cron import get_cron_service+ if module_enabled("calendar"):+ from deeptutor.services.cron import get_cron_service- cron_service = get_cron_service()- loop = asyncio.get_running_loop()+ cron_service = get_cron_service()+ loop = asyncio.get_running_loop()- def _notify_cron_change() -> None:- task = loop.create_task(- application_container.coordinator.submit_background_command(- BackgroundCommandKind.CRON_RELOAD+ def _notify_cron_change() -> None:+ task = loop.create_task(+ application_container.coordinator.submit_background_command(+ BackgroundCommandKind.CRON_RELOAD+ )+ )+ task.add_done_callback(+ lambda completed: completed.exception() if not completed.cancelled() else None)- )- task.add_done_callback(- lambda completed: completed.exception() if not completed.cancelled() else None- )- cron_service.change_notifier = _notify_cron_change+ cron_service.change_notifier = _notify_cron_changeexcept Exception:logger.exception("Failed to configure cron change notifications")+ from deeptutor.modules.services import module_service_callbacksfrom deeptutor.runtime.background_leader import BackgroundLeaderSupervisorbackground_supervisor = BackgroundLeaderSupervisor(application_container.coordinator,application_container.worker_id,- start_callbacks=[- _start_partners,- _start_cron,- _start_github_sync,- _start_web_source_sync,- ],- stop_callbacks=[- _stop_partners,- _stop_cron,- _stop_github_sync,- _stop_web_source_sync,- ],+ start_callbacks=module_service_callbacks("start", application_container),+ stop_callbacks=module_service_callbacks("stop", application_container),recovery_callback=application_container.recover_once,control_callback=_handle_background_command,renew_interval_seconds=application_container.settings.renew_interval_seconds,@@ -323,19 +280,20 @@ async def lifespan(app: FastAPI):# Migrate any v1 memory files (PROFILE.md / SOUL.md / SUMMARY.md) into a# backup folder so the v2 three-layer subsystem starts clean.try:- from deeptutor.services.memory import (- migrate_partner_surface_if_needed,- migrate_v1_if_needed,- )- from deeptutor.services.path_service import get_path_service-- get_path_service().migrate_legacy_memory_markdown()- backup = migrate_v1_if_needed()- if backup is not None:- logger.info("v1 memory archived to %s", backup)- # Rename the legacy ``tutorbot`` memory surface (footnote refs, L2- # doc, snapshot/trace dirs, L3 meta keys) to ``partner``.- migrate_partner_surface_if_needed()+ if module_enabled("memory"):+ from deeptutor.services.memory import (+ migrate_partner_surface_if_needed,+ migrate_v1_if_needed,+ )+ from deeptutor.services.path_service import get_path_service++ get_path_service().migrate_legacy_memory_markdown()+ backup = migrate_v1_if_needed()+ if backup is not None:+ logger.info("v1 memory archived to %s", backup)+ # Rename the legacy ``tutorbot`` memory surface (footnote refs, L2+ # doc, snapshot/trace dirs, L3 meta keys) to ``partner``.+ migrate_partner_surface_if_needed()except Exception as e:logger.warning(f"v1 memory migration failed: {e}")@@ -346,7 +304,8 @@ async def lifespan(app: FastAPI):app.state.ready = Falselogger.info("Application shutdown")- install_progress_ports(broadcast=None, emit_task_event=None)+ if module_enabled("knowledge"):+ install_progress_ports(broadcast=None, emit_task_event=None)try:await background_supervisor.close()@@ -412,6 +371,21 @@ app = FastAPI(# See: https://github.com/HKUDS/DeepTutor/issues/112redirect_slashes=False,)++from deeptutor.core.errors import AccessError+from deeptutor.modules.catalog import ModuleUnavailable++[email protected]_handler(AccessError)+async def access_error_handler(request: Request, exc: AccessError):+ return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})++[email protected]_handler(ModuleUnavailable)+async def module_unavailable_handler(request: Request, exc: ModuleUnavailable):+ return JSONResponse(status_code=409, content={"detail": str(exc)})++app.add_middleware(WorkspaceActivityMiddleware)@@ -538,308 +512,9 @@ _router_loader = RouterLoader(app, lazy=os.environ.get("DEEPTUTOR_CHAT_ENGINE") == "typescript-native")-# Auth router is public — login/logout/register/status require no token-_router_loader.include("deeptutor.api.routers.auth:router", prefix="/api/auth", tags=["auth"])-_router_loader.include(- "deeptutor.api.routers.outputs:router", prefix="/files/outputs", tags=["outputs"]-)-_router_loader.include(- "deeptutor.api.routers.workspace:files_router",- prefix="/files/workspace-items",- tags=["workspace"],-)--# All other routers require a valid session when AUTH_ENABLED=true.-# require_auth is a no-op when AUTH_ENABLED=false, so this is safe for local use.-from deeptutor.api.routers.auth import ( # noqa: E402- require_admin,- require_auth,- require_learning_surface,-)--_auth = [Depends(require_learning_surface)]-# Partner data is anchored at the admin workspace (data/partners) and shared-# process-wide, so management is admin-gated in multi-user deployments-# (single-user local runs are implicitly admin — no behaviour change there).-_admin = [Depends(require_admin)]--_router_loader.include(- "deeptutor.api.routers.multi_user:router",- prefix="/api/multi-user",- tags=["multi-user"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.question:router",- prefix="/api/question",- tags=["question"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.knowledge:router",- prefix="/api",- tags=["knowledge-bases"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.file_preview:router",- prefix="/api/file-preview",- tags=["file-preview"],- dependencies=[Depends(require_auth)],-)-_router_loader.include(- "deeptutor.api.routers.imports:router",- prefix="/api/imports",- tags=["imports"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.dashboard:router",- prefix="/api/dashboard",- tags=["dashboard"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.mastery_path:router",- prefix="/api/mastery-paths",- tags=["mastery-path"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.file_library:router",- prefix="/files/library",- tags=["library"],- dependencies=_auth,-)-# WebSocket handlers authenticate inside the connection before ``accept``.-# Keep them off HTTP router dependencies: ``require_learning_surface`` takes a-# Request, which FastAPI cannot construct for a WebSocket scope.-_router_loader.include(- "deeptutor.api.routers.question:ws_router", prefix="/ws/questions", tags=["question"]-)-_router_loader.include(- "deeptutor.api.routers.knowledge:ws_router", prefix="/ws", tags=["knowledge-bases"]-)-_router_loader.include(- "deeptutor.api.routers.mastery_path:ws_router",- prefix="/ws",- tags=["mastery-path"],-)-_router_loader.include(- "deeptutor.api.routers.co_writer:router", prefix="/api", tags=["documents"], dependencies=_auth-)-_router_loader.include(- "deeptutor.api.routers.notebook:router", prefix="/api", tags=["notebooks"], dependencies=_auth-)-_router_loader.include(- "deeptutor.api.routers.task_board:router",- prefix="/api/task-board",- tags=["task-board"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.calendar:router",- prefix="/api/calendar",- tags=["calendar"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.book:router", prefix="/api", tags=["books"], dependencies=_auth-)-_router_loader.include("deeptutor.api.routers.book:ws_router", prefix="/ws", tags=["books"])-_router_loader.include(- "deeptutor.api.routers.reading:router",- prefix="/api/reading",- tags=["reading"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.reading_extensions:router",- prefix="/api/reading",- tags=["reading-extensions"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.memory:router", prefix="/api/memory", tags=["memory"], dependencies=_auth-)-_router_loader.include(- "deeptutor.api.routers.learning_journal:router",- prefix="/api/learning-journal",- tags=["learning-journal"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.capabilities_settings:router",- prefix="/api/capabilities",- tags=["capabilities"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.capabilities:router",- prefix="/api/capabilities",- tags=["capabilities"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.sessions:router",- prefix="/api/sessions",- tags=["sessions"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.question_notebook:router",- prefix="/api/question-notebook",- tags=["question-notebook"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.practice:router",- prefix="/api/question-notebook/practice",- tags=["practice"],- dependencies=_auth,-)-# Public UI-settings read (auth pages bootstrap the interface language-# before a session exists, so GET /api/settings/ui must not be gated-# by _auth). Mounted first so the path resolves here, not on the gated-# settings router below.-_router_loader.include(- "deeptutor.api.routers.settings:public_router",- prefix="/api/settings",- tags=["settings"],-)-_router_loader.include(- "deeptutor.api.routers.settings:router",- prefix="/api/settings",- tags=["settings"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.workspace:settings_router",- prefix="/api/settings/workspace",- tags=["workspace-settings"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.video_learning:settings_router",- prefix="/api/settings/video-learning",- tags=["video-learning-settings"],- dependencies=_admin,-)-_router_loader.include(- "deeptutor.api.routers.mcp_settings:router",- prefix="/api/settings/mcp",- tags=["mcp-settings"],- dependencies=_auth,-)-# Per-user MCP servers. Deliberately only ``_auth``: the router's own routes-# resolve the owner server-side, and everything a non-admin can reach through it-# is remote-transport-only (see the module docstring). The admin registry above-# keeps its own ``require_admin``.-_router_loader.include(- "deeptutor.api.routers.space_mcp:router",- prefix="/api/space/mcp",- tags=["space-mcp"],- dependencies=_auth,-)-# CLI apps. Only ``_auth`` here as well, but for a different reason: the two-# routes that install or remove an app carry their own ``require_admin``, and-# what is left for an ordinary account is reading the catalog and toggling its-# own preference among apps an administrator already granted it.-_router_loader.include(- "deeptutor.api.routers.space_cli_apps:router",- prefix="/api/space/cli-apps",- tags=["space-cli-apps"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.skills:router", prefix="/api/skills", tags=["skills"], dependencies=_auth-)-_router_loader.include(- "deeptutor.api.routers.subagents:router",- prefix="/api/subagents",- tags=["subagents"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.personas:router", prefix="/api", tags=["personas"], dependencies=_auth-)-_router_loader.include(- "deeptutor.api.routers.plugins:router", prefix="/api/plugins", tags=["plugins"]-)-_router_loader.include(- "deeptutor.api.routers.tools:router", prefix="/api/tools", tags=["tools"], dependencies=_auth-)-_router_loader.include(- "deeptutor.api.routers.system:router", prefix="/api/system", tags=["system"], dependencies=_auth-)-_router_loader.include(- "deeptutor.api.routers.voice:router", prefix="/api/voice", tags=["voice"], dependencies=_auth-)-_router_loader.include(- "deeptutor.api.routers.video_learning:router",- prefix="/api/video-learning",- tags=["video-learning"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.visualizers:router",- prefix="/api/visualizers",- tags=["visualizers"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.agent_config:router",- prefix="/api/agent-config",- tags=["agent-config"],- dependencies=_auth,-)-# Partners are per-user resources now: anyone may build their own, and an admin-# may assign theirs to others. Only ``_auth`` here — every route in the router-# declares whether it needs *use* or *manage* rights on the partner it names-# (see ``multi_user.partner_access``), which a blanket admin gate could not-# express.-_router_loader.include(- "deeptutor.api.routers.partners:router",- prefix="/api/partners",- tags=["partners"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.partner_groups:router",- prefix="/api/partner-groups",- tags=["partner-groups"],- dependencies=_auth,-)-_router_loader.include(- "deeptutor.api.routers.partners:ws_router", prefix="/ws/partners", tags=["partners"]-)-_router_loader.include(- "deeptutor.api.routers.partner_groups:ws_router",- prefix="/ws/partner-groups",- tags=["partner-groups"],-)-_router_loader.include(- "deeptutor.api.routers.attachments:router",- prefix="/files/attachments",- tags=["attachments"],- dependencies=_auth,-)--# MarginNote 4 device bridge — pairing/management routes carry _auth in-router;-# sync/heartbeat use device-token auth (the Add-on has no session).-_router_loader.include(- "deeptutor.api.routers.marginnote4:router",- prefix="/api/marginnote4",- tags=["marginnote4"],-)--# Unified WebSocket endpoint — auth is checked inside the handler (WebSockets-# cannot use FastAPI dependencies in the standard way)-_router_loader.include("deeptutor.api.routers.unified_ws:router", tags=["unified-ws"])+from deeptutor.api.module_routes import mount_module_routes-# Quiz AI-judge WebSocket — same caveat as unified_ws above; auth is checked-# inside the handler so the WS upgrade isn't rejected by an HTTP-style dep.-_router_loader.include("deeptutor.api.routers.quiz_judge:router", prefix="/ws", tags=["quiz-judge"])+mount_module_routes(app, _router_loader)@app.get("/")diff --git a/deeptutor/api/module_routes.py b/deeptutor/api/module_routes.pynew file mode 100644index 000000000..638cb720a--- /dev/null+++ b/deeptutor/api/module_routes.py@@ -0,0 +1,42 @@+"""Assemble installed modules without changing their authentication policies."""++from fastapi import Depends, FastAPI++from deeptutor.api.router_loader import RouterLoader+from deeptutor.modules.catalog import manifests, module_enabled+++def mount_module_routes(app: FastAPI, loader: RouterLoader) -> None:+ from deeptutor.api.routers.auth import require_admin, require_auth, require_learning_surface++ policies = {+ "public": [],+ "authenticated": [Depends(require_auth)],+ "learning": [Depends(require_learning_surface)],+ "admin": [Depends(require_admin)],+ }+ routes = [+ route+ for name, module in manifests().items()+ if module_enabled(name)+ for route in module["routes"]+ ]+ unavailable = tuple(+ prefix+ for name, row in manifests().items()+ if not module_enabled(name)+ for prefix in row.get("http_paths", [])+ )+ for route in sorted(routes, key=lambda row: row["order"]):+ loader.include(+ route["reference"],+ **route["options"],+ exclude_paths=unavailable,+ dependencies=policies[route["auth"]],+ )+ loader.include(+ "deeptutor.api.routers.modules:router",+ prefix="/api/modules",+ tags=["modules"],+ dependencies=[Depends(require_auth)],+ )diff --git a/deeptutor/api/router_index.json b/deeptutor/api/router_index.jsonindex 56e68af38..b81f72cdd 100644--- a/deeptutor/api/router_index.json+++ b/deeptutor/api/router_index.json@@ -1,5 +1,5 @@{- "fingerprint": "e6abfcb6ec2f17779189936a7f321054d1f1225282134d9a36dbc09eeec341e4",+ "fingerprint": "84bafefe60e0e8504f8ac797383af66cf2066e325c9a441df16b889644421dc9","routers": {"deeptutor.api.routers.auth:router": [{@@ -5713,6 +5713,16 @@"kind": "websocket","methods": []}+ ],+ "deeptutor.api.routers.modules:router": [+ {+ "path": "",+ "name": "list_modules",+ "kind": "http",+ "methods": [+ "GET"+ ]+ }]}}diff --git a/deeptutor/api/router_loader.py b/deeptutor/api/router_loader.pyindex a83d1b494..8d15fbc7d 100644--- a/deeptutor/api/router_loader.py+++ b/deeptutor/api/router_loader.py@@ -7,6 +7,7 @@ index disables deferral; OpenAPI expands every router before schema generation.from __future__ import annotations+from copy import copyimport hashlibfrom importlib import import_moduleimport json@@ -106,14 +107,28 @@ class RouterLoader:app.openapi = openapi- def include(self, reference: str, **options: Any) -> None:- if reference in self.index:+ def include(+ self, reference: str, *, exclude_paths: tuple[str, ...] = (), **options: Any+ ) -> None:+ if reference in self.index and not exclude_paths:self.app.router.routes.append(DeferredRouter(self.app, reference, options, self.index[reference]))else:module, attribute = reference.split(":", 1)router = getattr(import_module(module), attribute)+ if exclude_paths:+ router = copy(router)+ prefix = options.get("prefix", "")+ router.routes = [+ route+ for route in router.routes+ if not any(+ prefix + getattr(route, "path", "") == path+ or (prefix + getattr(route, "path", "")).startswith(path + "/")+ for path in exclude_paths+ )+ ]self.records[reference] = routerself.app.include_router(router, **options)diff --git a/deeptutor/api/routers/dashboard.py b/deeptutor/api/routers/dashboard.pyindex a27728edd..313e26582 100644--- a/deeptutor/api/routers/dashboard.py+++ b/deeptutor/api/routers/dashboard.py@@ -106,18 +106,22 @@ async def refresh_starter_suggestions():@router.get("/learning-index")async def get_learning_index():"""Read-only entry points into the request's workspace."""- from deeptutor.api.routers.book import list_books- from deeptutor.api.routers.mastery_path import list_topics- from deeptutor.api.routers.reading import list_workspaces+ from deeptutor.modules.catalog import module_enabledfrom deeptutor.multi_user.learning_access import learning_surface_allowedasync def books():+ from deeptutor.api.routers.book import list_books+return (await list_books())["books"]async def mastery():+ from deeptutor.api.routers.mastery_path import list_topics+return (await list_topics())["topics"]async def reading():+ from deeptutor.api.routers.reading import list_workspaces+return (await list_workspaces(search=""))["workspaces"]async def watching():@@ -151,7 +155,8 @@ async def get_learning_index():# Calling a route function directly bypasses its HTTP dependencies.# Never load a source that the learner could not open individually.result[kind] = []- if not learning_surface_allowed(surface):+ owner = {"watching": "reading", "practice": "notebook"}.get(kind, kind)+ if not module_enabled(owner) or not learning_surface_allowed(surface):continuetry:result[kind] = await _workspace_rows(reader)diff --git a/deeptutor/api/routers/knowledge.py b/deeptutor/api/routers/knowledge.pyindex 959d7cb5b..1a29ea071 100644--- a/deeptutor/api/routers/knowledge.py+++ b/deeptutor/api/routers/knowledge.py@@ -79,7 +79,6 @@ from deeptutor.services.rag.factory import (normalize_provider_name,provider_uses_embedding_versions,)-from deeptutor.services.rag.file_routing import FileTypeRouterfrom deeptutor.services.rag.linked_kb import (LINKABLE_PROVIDERS,assert_path_allowed,@@ -108,6 +107,7 @@ from deeptutor.utils.document_extractor import ()from deeptutor.utils.document_validator import DocumentValidatorfrom deeptutor.utils.error_utils import format_exception_message+from deeptutor.utils.file_types import FileTypeRouter# Initialize logger with configconfig = load_config_with_main("main.yaml", PROJECT_ROOT)diff --git a/deeptutor/api/routers/modules.py b/deeptutor/api/routers/modules.pynew file mode 100644index 000000000..79af13b41--- /dev/null+++ b/deeptutor/api/routers/modules.py@@ -0,0 +1,12 @@+"""Read-only deployment inventory; code mutations run in the offline CLI."""++from fastapi import APIRouter++from deeptutor.modules.catalog import module_statuses++router = APIRouter()+++def list_modules():+ return {"modules": module_statuses()}diff --git a/deeptutor/api/routers/multi_user.py b/deeptutor/api/routers/multi_user.pyindex a96675292..441389e02 100644--- a/deeptutor/api/routers/multi_user.py+++ b/deeptutor/api/routers/multi_user.py@@ -14,7 +14,7 @@ from fastapi import APIRouter, Depends, HTTPExceptionfrom pydantic import BaseModel, Field, StrictBool, field_validatorfrom deeptutor.api.routers.auth import require_admin, require_auth-from deeptutor.knowledge.manager import KnowledgeBaseManager+from deeptutor.modules.catalog import module_enabled, require_modulefrom deeptutor.multi_user.audit import log_admin_action, log_guardian_actionfrom deeptutor.multi_user.book_permission import (BookDefaultLevel,@@ -56,8 +56,6 @@ from deeptutor.multi_user.paths import (get_path_service_for_scope,scope_for_user,)-from deeptutor.reading import ReadingStore-from deeptutor.reading.extensions import get_reading_extension_registryfrom deeptutor.services.auth import POCKETBASE_ENABLED, hash_passwordfrom deeptutor.services.config.model_catalog import ModelCatalogService@@ -193,6 +191,10 @@ def _admin_catalog_summary() -> dict[str, list[dict[str, Any]]]:def _admin_kb_summary() -> list[dict[str, Any]]:+ if not module_enabled("knowledge"):+ return []+ from deeptutor.knowledge.manager import KnowledgeBaseManager+manager = KnowledgeBaseManager(base_dir=str(admin_kb_base_dir()))return [{@@ -220,6 +222,8 @@ def _admin_partner_summary() -> list[dict[str, Any]]:soul, which people write personally) by a single click. Identity only: nochannel wiring or model selection leaks into the assignable summary."""+ if not module_enabled("partners"):+ return []from deeptutor.services.partners import get_partner_manageradmin_id = get_current_user().id@@ -240,6 +244,10 @@ def _reading_root(service: Any) -> Path:def _admin_reading_summary() -> list[dict[str, Any]]:+ if not module_enabled("reading"):+ return []+ from deeptutor.reading import ReadingStore+store = ReadingStore(_reading_root(get_admin_path_service()))return [manifest.to_dict() for manifest in store.list_materials()]@@ -255,6 +263,9 @@ def _stage_assigned_materials(user_id: str, grant: dict[str, Any]) -> None:if not material_ids:return+ require_module("reading")+ from deeptutor.reading import ReadingStore+admin_root = _reading_root(get_admin_path_service())admin_store = ReadingStore(admin_root)user_service = get_path_service_for_scope(scope_for_user(user_id, is_admin=False))@@ -281,9 +292,7 @@ def _validate_reading_policy(grant: dict[str, Any]) -> None:reading = policy.get("reading") if isinstance(policy, dict) else Noneif not isinstance(reading, dict):return- allowed_extensions = {- extension.manifest.id for extension in get_reading_extension_registry().all()- }+ allowed_extensions = {extension.manifest.id for extension in _reading_extensions()}unknown = sorted(set(reading.get("extensions") or []) - allowed_extensions)if unknown:raise ValueError(f"Unknown reading extensions: {', '.join(unknown)}")@@ -365,7 +374,7 @@ async def admin_resources(_: object = Depends(require_admin)) -> dict[str, Any]:"partners": _admin_partner_summary(),"reading_materials": _admin_reading_summary(),"reading_extensions": [- extension.manifest.model_dump() for extension in get_reading_extension_registry().all()+ extension.manifest.model_dump() for extension in _reading_extensions()],"tools": tool_options["tools"],"mcp_tools": tool_options["mcp_tools"],@@ -648,7 +657,7 @@ async def get_guardian_restrictions(return {"restrictions": restrictions,"available_extensions": [- extension.manifest.model_dump() for extension in get_reading_extension_registry().all()+ extension.manifest.model_dump() for extension in _reading_extensions()],}@@ -662,9 +671,7 @@ async def put_guardian_restrictions(learner_username, learner_record, actor_user_id, is_admin = _require_guardian_access(current, learner_user_id, "manage_restrictions")- available_extensions = {- extension.manifest.id for extension in get_reading_extension_registry().all()- }+ available_extensions = {extension.manifest.id for extension in _reading_extensions()}unknown_extensions = sorted(set(payload.extensions) - available_extensions)if unknown_extensions:raise HTTPException(@@ -926,3 +933,11 @@ async def admin_install_skill(@router.get("/users")async def multi_user_list_users(_: object = Depends(require_admin)) -> dict[str, Any]:return {"users": list_user_info()}+++def _reading_extensions():+ if not module_enabled("reading"):+ return ()+ from deeptutor.reading.extensions import get_reading_extension_registry++ return get_reading_extension_registry().all()diff --git a/deeptutor/api/routers/outputs.py b/deeptutor/api/routers/outputs.pyindex 79e205175..97f495cde 100644--- a/deeptutor/api/routers/outputs.py+++ b/deeptutor/api/routers/outputs.py@@ -12,7 +12,6 @@ from deeptutor.multi_user.context import get_current_user_or_nonefrom deeptutor.multi_user.partner_access import visible_partnersfrom deeptutor.multi_user.paths import get_current_path_service, get_path_service_for_scopefrom deeptutor.services.auth import TokenPayload-from deeptutor.services.partners.scope import partner_scopefrom deeptutor.services.path_service import PathServicerouter = APIRouter()@@ -58,10 +57,13 @@ def _resolve_partner_output(relative_path: str) -> Path | None:the same relative path colliding across multiple partners is vanishinglyunlikely. Fail closed anyway: only a unique partner match is served."""+ from deeptutor.modules.catalog import module_enabledfrom deeptutor.services.workspace.context import current_workspace_id- if current_workspace_id():+ if current_workspace_id() or not module_enabled("partners"):return None+ from deeptutor.services.partners.scope import partner_scope+matches: list[Path] = []for partner in visible_partners():partner_id = str(partner.get("partner_id") or "").strip()diff --git a/deeptutor/api/routers/sessions.py b/deeptutor/api/routers/sessions.pyindex cb1cba300..0784f6558 100644--- a/deeptutor/api/routers/sessions.py+++ b/deeptutor/api/routers/sessions.py@@ -13,8 +13,7 @@ from fastapi import APIRouter, HTTPException, Query, Requestfrom pydantic import BaseModel, Field, field_validatorfrom deeptutor.core.turn_request import TurnRequest-from deeptutor.learning.storage import LearningStore-from deeptutor.reading.catalog_store import ReadingCatalogStore+from deeptutor.modules.catalog import module_enabledfrom deeptutor.response_languages import validate_reply_language_overridefrom deeptutor.services.session import get_session_store, get_sqlite_session_storefrom deeptutor.services.session.organization import (@@ -524,7 +523,12 @@ async def rename_session(session_id: str, payload: SessionRenameRequest):# The reader keeps its own list of a collection's conversations; the# sidebar is where they are renamed, so the list has to hear about it.try:- await asyncio.to_thread(ReadingCatalogStore().retitle_session, session_id, payload.title)+ if module_enabled("reading"):+ from deeptutor.reading.catalog_store import ReadingCatalogStore++ await asyncio.to_thread(+ ReadingCatalogStore().retitle_session, session_id, payload.title+ )except Exception:logger.exception("failed to retitle reading conversation %s", session_id)session = await store.get_session(session_id)@@ -682,7 +686,10 @@ async def delete_session(session_id: str):async def _cleanup_deleted_session(session_id: str) -> None:try:- await asyncio.to_thread(LearningStore().detach_session, session_id)+ if module_enabled("mastery"):+ from deeptutor.learning.storage import LearningStore++ await asyncio.to_thread(LearningStore().detach_session, session_id)except Exception:logger.exception("failed to detach mastery paths for session %s", session_id)try:@@ -690,7 +697,10 @@ async def _cleanup_deleted_session(session_id: str) -> None:except Exception:logger.exception("failed to clean up attachments for session %s", session_id)try:- await asyncio.to_thread(ReadingCatalogStore().forget_session, session_id)+ if module_enabled("reading"):+ from deeptutor.reading.catalog_store import ReadingCatalogStore++ await asyncio.to_thread(ReadingCatalogStore().forget_session, session_id)except Exception:logger.exception("failed to detach reading collections for session %s", session_id)diff --git a/deeptutor/api/routers/settings.py b/deeptutor/api/routers/settings.pyindex 17c9cdc09..983dff8ec 100644--- a/deeptutor/api/routers/settings.py+++ b/deeptutor/api/routers/settings.py@@ -600,7 +600,7 @@ def _require_codex_oauth_actor() -> None:including signing them out. Partners inherit the owner's login at calltime and need no lifecycle of their own."""- from deeptutor.services.partners.scope import is_partner_user_id+ from deeptutor.core.identities import is_partner_user_idif is_partner_user_id(get_current_user().id):raise HTTPException(diff --git a/deeptutor/api/routers/subagents.py b/deeptutor/api/routers/subagents.pyindex 1b631be1b..a7349da81 100644--- a/deeptutor/api/routers/subagents.py+++ b/deeptutor/api/routers/subagents.py@@ -23,9 +23,7 @@ from fastapi.responses import StreamingResponsefrom pydantic import BaseModel, Fieldfrom deeptutor.api.routers.auth import require_admin-from deeptutor.knowledge.kb_types import SUBAGENT_KB_TYPEfrom deeptutor.multi_user.knowledge_access import account_kb_manager-from deeptutor.services.rag.linked_kb import assert_path_allowedfrom deeptutor.services.subagent import (detect_all,list_backend_kinds,@@ -91,6 +89,11 @@ async def sync_backend(kind: str):@router.get("/connections")async def list_connections():"""List the current user's connected subagents."""+ from deeptutor.modules.catalog import require_module++ require_module("knowledge")+ from deeptutor.knowledge.kb_types import SUBAGENT_KB_TYPE+manager = account_kb_manager()connections = []for name in manager.list_knowledge_bases():@@ -130,10 +133,15 @@ async def create_connection(payload: ConnectSubagentRequest):raw_cwd = (payload.cwd or "").strip()if raw_cwd and backend is not None and getattr(backend, "local_cli", True):try:+ from deeptutor.services.rag.linked_kb import assert_path_allowed+resolved_cwd = str(assert_path_allowed(raw_cwd))except ValueError as exc:raise HTTPException(status_code=400, detail=str(exc)) from exc+ from deeptutor.modules.catalog import require_module++ require_module("knowledge")try:manager = account_kb_manager()entry = manager.register_subagent_connection(name, agent_kind, cwd=resolved_cwd)@@ -155,6 +163,11 @@ async def create_connection(payload: ConnectSubagentRequest):@router.delete("/connections/{name}")async def delete_connection(name: str):"""Disconnect a subagent (removes the pointer KB; touches no files)."""+ from deeptutor.modules.catalog import require_module++ require_module("knowledge")+ from deeptutor.knowledge.kb_types import SUBAGENT_KB_TYPE+manager = account_kb_manager()meta = manager.get_metadata(name)if not isinstance(meta, dict) or meta.get("type") != SUBAGENT_KB_TYPE:@@ -189,6 +202,11 @@ async def message_connection(name: str, payload: SubagentMessageRequest):if not message:raise HTTPException(status_code=400, detail="A non-empty 'message' is required.")+ from deeptutor.modules.catalog import require_module++ require_module("knowledge")+ from deeptutor.knowledge.kb_types import SUBAGENT_KB_TYPE+manager = account_kb_manager()meta = manager.get_metadata(name)if not isinstance(meta, dict) or meta.get("type") != SUBAGENT_KB_TYPE:diff --git a/deeptutor/api/routers/workspace.py b/deeptutor/api/routers/workspace.pyindex f0c3717b8..77e759a3a 100644--- a/deeptutor/api/routers/workspace.py+++ b/deeptutor/api/routers/workspace.py@@ -13,7 +13,6 @@ from deeptutor.api.routers.auth import require_authfrom deeptutor.multi_user.partner_access import visible_partnersfrom deeptutor.multi_user.paths import user_contextfrom deeptutor.services.auth import TokenPayload-from deeptutor.services.partners.scope import partner_userfrom deeptutor.services.workspace import (WorkspaceError,WorkspaceItem,@@ -319,6 +318,8 @@ def _resolve_partner_item(partner_id = str(partner.get("partner_id") or "").strip()if not partner_id:continue+ from deeptutor.services.partners.scope import partner_user+with user_context(partner_user(partner_id)):try:return get_content_workspace_service().resolve_published_item(diff --git a/deeptutor/app/container.py b/deeptutor/app/container.pyindex 961d1dc5e..36aa50cdd 100644--- a/deeptutor/app/container.py+++ b/deeptutor/app/container.py@@ -100,6 +100,7 @@ class ApplicationContainer:)self._recovery_services: dict[str, TurnRecoveryService] = {}self._started = False+ self._module_lease = None@classmethoddef build(cls) -> "ApplicationContainer":@@ -122,26 +123,41 @@ class ApplicationContainer:async def start(self) -> None:if self._started:return- if not await self.coordinator.health():- raise RuntimeConfigurationError(- "Turn coordination backend is unavailable; refusing to start"- )- self._started = True+ from deeptutor.modules.lifecycle import environment_lease++ lease = environment_lease()+ lease.__enter__()+ self._module_lease = lease+ try:+ if not await self.coordinator.health():+ raise RuntimeConfigurationError(+ "Turn coordination backend is unavailable; refusing to start"+ )+ self._started = True+ except BaseException:+ lease.__exit__(None, None, None)+ self._module_lease = None+ raiseasync def close(self) -> None:if not self._started:return- # Cancel active turns now so their finally blocks can persist shutdown- # state and release subprocesses within the launcher grace period.- await self.runtime_registry.close(drain_timeout_seconds=0.0)- from deeptutor.runtime.memory_reclaim import cancel_idle_reclaim- from deeptutor.runtime.ts_engine import close_engine_clients-- cancel_idle_reclaim()- await close_engine_clients()- with contextlib.suppress(Exception):- await self.coordinator.close()- self._started = False+ try:+ # Await cancellation cleanup before releasing the environment lease.+ await self.runtime_registry.close(drain_timeout_seconds=0.0)+ from deeptutor.runtime.memory_reclaim import cancel_idle_reclaim+ from deeptutor.runtime.ts_engine import close_engine_clients++ cancel_idle_reclaim()+ await close_engine_clients()+ with contextlib.suppress(Exception):+ await self.coordinator.close()+ finally:+ self._started = False+ lease = getattr(self, "_module_lease", None)+ if lease is not None:+ lease.__exit__(None, None, None)+ self._module_lease = Noneasync def recover_once(self) -> None:"""Recover expired turns across every registered user repository.@@ -295,6 +311,10 @@ class ApplicationContainer:async def adopt_all_book_chat_sessions(self) -> list[dict[str, Any]]:"""Link page chats to their books in every account and workspace."""+ from deeptutor.modules.catalog import module_enabled++ if not module_enabled("books"):+ return []from deeptutor.book.chat_sessions import adopt_book_chat_sessionsfrom deeptutor.multi_user.paths import user_contextfrom deeptutor.services.workspace import get_content_workspace_servicediff --git a/deeptutor/app/facade.py b/deeptutor/app/facade.pyindex e3dd1d5d3..c6ac9600a 100644--- a/deeptutor/app/facade.py+++ b/deeptutor/app/facade.py@@ -4,14 +4,10 @@ from __future__ import annotationsfrom dataclasses import asdict, dataclassfrom functools import wraps-import importlib.utilimport inspectimport json-import shutilfrom typing import Any, AsyncIterator-from deeptutor.services.notebook import get_notebook_manager-from .container import get_application_containerfrom .contracts import TurnRequest@@ -77,6 +73,11 @@ class DeepTutorApp:@propertydef notebooks(self):+ from deeptutor.modules.catalog import require_module++ require_module("notebook")+ from deeptutor.services.notebook import get_notebook_manager+with self._workspace_context():return get_notebook_manager()@@ -115,30 +116,15 @@ class DeepTutorApp:def get_capability_availability(self, capability: str) -> CapabilityAvailability:resolved = self.resolve_capability(capability)- if resolved == "math_animator":- available = importlib.util.find_spec("manim") is not None- return CapabilityAvailability(- name=resolved,- available=available,- install_hint=(- ""- if available- else "Install with `pip install -e '.[math-animator]'` "- "or `pip install -r requirements/math-animator.txt`."- ),- )- if resolved == "video_lesson":- available = all(shutil.which(tool) is not None for tool in ("node", "npm"))- return CapabilityAvailability(- name=resolved,- available=available,- install_hint=(- ""- if available- else "Install Node.js 22+ (with npm). Remotion and its WebAssembly sandbox are prepared on first use."- ),- )- return CapabilityAvailability(name=resolved, available=True)+ from deeptutor.modules.catalog import contribution_owner, module_statuses++ owner = contribution_owner("capabilities", resolved)+ status = next(row for row in module_statuses() if row["id"] == owner)+ return CapabilityAvailability(+ name=resolved,+ available=status["ready"],+ install_hint="; ".join(status["issues"]) if not status["ready"] else "",+ )async def start_turn(self, request: TurnRequest | dict[str, Any]diff --git a/deeptutor/book/blocks/animation.py b/deeptutor/book/blocks/animation.pyindex e69c30879..c0061788f 100644--- a/deeptutor/book/blocks/animation.py+++ b/deeptutor/book/blocks/animation.py@@ -30,6 +30,9 @@ class AnimationGenerator(BlockGenerator):async def _generate(self, ctx: BlockContext) -> tuple[dict[str, Any], list[SourceAnchor], dict[str, Any]]:+ from deeptutor.modules.catalog import require_module++ require_module("renderer-manim")if importlib.util.find_spec("manim") is None:raise GenerationFailure("AnimationGenerator requires the optional math-animator extras. "diff --git a/deeptutor/book/context.py b/deeptutor/book/context.pyindex 64c664c6c..ddf598526 100644--- a/deeptutor/book/context.py+++ b/deeptutor/book/context.py@@ -11,7 +11,7 @@ depend on FastAPI so it remains cheap to unit test and reuse.from __future__ import annotations-from dataclasses import dataclass, field+from dataclasses import dataclassimport refrom typing import Any, Iterable, Sequence@@ -36,13 +36,7 @@ class NormalizedBookReference:return {"book_id": self.book_id, "page_ids": list(self.page_ids)}-@dataclass-class BookContextResult:- """Serialized book context plus non-fatal issues encountered while loading."""-- text: str = ""- references: list[dict[str, Any]] = field(default_factory=list)- warnings: list[str] = field(default_factory=list)+from deeptutor.core.source_context import SourceContext as BookContextResultdef normalize_book_references(value: Any) -> list[NormalizedBookReference]:diff --git a/deeptutor/book/inputs.py b/deeptutor/book/inputs.pyindex a11707908..d06589458 100644--- a/deeptutor/book/inputs.py+++ b/deeptutor/book/inputs.py@@ -186,6 +186,9 @@ async def _resolve_notebook_context("""Return (context_text, record_count). 0 records → empty context."""if not notebook_refs:return "", 0+ from deeptutor.modules.catalog import require_module++ require_module("notebook")try:from deeptutor.services.notebook import notebook_managerdiff --git a/deeptutor/capabilities/ask_questions/capability.py b/deeptutor/capabilities/ask_questions/capability.pyindex 1ffea8ea1..0f41acad3 100644--- a/deeptutor/capabilities/ask_questions/capability.py+++ b/deeptutor/capabilities/ask_questions/capability.py@@ -6,29 +6,18 @@ from typing import castfrom deeptutor.agents.chat.agentic_pipeline import AgenticChatPipelinefrom deeptutor.core.capability_protocol import (- CapabilityManifest,StreamBusProtocol,TurnCapability,)from deeptutor.core.context import UnifiedContext-from deeptutor.runtime.request_contracts import get_capability_request_schema+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifestfrom deeptutor.runtime.stream_bus import StreamBusclass AskQuestionsCapability(TurnCapability):"""Start the selected turn with a context-aware question card."""- manifest = CapabilityManifest(- name="ask_questions",- description=(- "Ask the user high-value questions to fill in missing context, "- "then complete the original request with their answers."- ),- stages=["responding"],- tools_used=["ask_user"],- cli_aliases=["ask"],- request_schema=get_capability_request_schema("chat"),- )+ manifest = builtin_capability_manifest("ask_questions")async def run(self, context: UnifiedContext, stream: StreamBusProtocol) -> None:context.metadata["ask_questions_mode"] = Truediff --git a/deeptutor/capabilities/audio_overview/capability.py b/deeptutor/capabilities/audio_overview/capability.pyindex 360bdc061..4fd3e56f9 100644--- a/deeptutor/capabilities/audio_overview/capability.py+++ b/deeptutor/capabilities/audio_overview/capability.py@@ -11,29 +11,15 @@ from deeptutor.capabilities.audio_overview.pipeline import (AudioOverviewPipeline,)from deeptutor.capabilities.audio_overview.request_config import AudioOverviewRequestConfig-from deeptutor.core.capability_protocol import CapabilityManifest, StreamBusProtocol, TurnCapability+from deeptutor.core.capability_protocol import StreamBusProtocol, TurnCapabilityfrom deeptutor.core.context import UnifiedContextfrom deeptutor.i18n import StatusI18n-from deeptutor.runtime.request_contracts import get_capability_request_schema+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifestfrom deeptutor.runtime.stream_bus import StreamBusclass AudioOverviewCapability(TurnCapability):- manifest = CapabilityManifest(- name="audio_overview",- description="Create a grounded two-voice audio overview and transcript from a knowledge base.",- stages=["retrieving", "script_writing", "voice_generation", "publishing"],- tools_used=["rag"],- cli_aliases=["audio-overview", "overview"],- request_schema=get_capability_request_schema("audio_overview"),- config_defaults={- "topic": "",- "target_minutes": 5,- "host_voice": None,- "expert_voice": None,- "max_context_chunks": 6,- },- )+ manifest = builtin_capability_manifest("audio_overview")async def run(self, context: UnifiedContext, protocol_stream: StreamBusProtocol) -> None:stream = cast(StreamBus, protocol_stream)@@ -80,6 +66,9 @@ class AudioOverviewCapability(TurnCapability):RetrievedContext,SourceCitation,)+ from deeptutor.modules.catalog import require_module++ require_module("co-writer")from deeptutor.co_writer.storage import get_co_writer_storagenote = get_co_writer_storage().load_document(note_id)diff --git a/deeptutor/capabilities/mastery/capability.py b/deeptutor/capabilities/mastery/capability.pyindex 76fdae8b3..801a060eb 100644--- a/deeptutor/capabilities/mastery/capability.py+++ b/deeptutor/capabilities/mastery/capability.py@@ -28,14 +28,13 @@ from typing import castimport uuidfrom deeptutor.capabilities.mastery.pipeline import MasteryLoopPipeline-from deeptutor.capabilities.mastery.tools import MASTERY_TOOL_NAMESfrom deeptutor.core.capability_protocol import (- CapabilityManifest,StreamBusProtocol,TurnCapability,)from deeptutor.core.context import UnifiedContextfrom deeptutor.learning.identity import resolve_mastery_path_binding+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifestfrom deeptutor.runtime.stream_bus import StreamBus@@ -55,16 +54,7 @@ def resolve_mastery_path_id(context: UnifiedContext) -> str:class MasteryPathCapability(TurnCapability):- manifest = CapabilityManifest(- name="mastery_path",- description=(- "Mastery-based tutoring: a dedicated agent loop drives an adaptive "- "mastery path with a hard, per-type mastery gate and spaced review."- ),- stages=["responding"],- tools_used=[*MASTERY_TOOL_NAMES, "rag", "read_source", "ask_user"],- cli_aliases=["mastery"],- )+ manifest = builtin_capability_manifest("mastery_path")async def run(self, context: UnifiedContext, stream: StreamBusProtocol) -> None:binding = resolve_mastery_path_binding(diff --git a/deeptutor/capabilities/reading/mode.py b/deeptutor/capabilities/reading/mode.pyindex 66c95d44d..f7eecaa75 100644--- a/deeptutor/capabilities/reading/mode.py+++ b/deeptutor/capabilities/reading/mode.py@@ -29,27 +29,17 @@ from deeptutor.capabilities.reading.capability import (MODE_KEY,resolve_material_id,)-from deeptutor.capabilities.reading.tools import READING_TOOL_NAMESfrom deeptutor.core.capability_protocol import (- CapabilityManifest,StreamBusProtocol,TurnCapability,)from deeptutor.core.context import UnifiedContext+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifestfrom deeptutor.runtime.stream_bus import StreamBusclass ImmersiveReadingCapability(TurnCapability):- manifest = CapabilityManifest(- name="immersive_reading",- description=(- "Read a document alongside the assistant, which cites the exact "- "page or section behind every claim."- ),- stages=["responding"],- tools_used=[*READING_TOOL_NAMES, "web_search", "exec", "reason"],- cli_aliases=["reading", "read"],- )+ manifest = builtin_capability_manifest("immersive_reading")async def run(self, context: UnifiedContext, stream: StreamBusProtocol) -> None:# Normalised so the flag and the id can never disagree: the loopdiff --git a/deeptutor/capabilities/registry.py b/deeptutor/capabilities/registry.pyindex e35aa8879..ace540054 100644--- a/deeptutor/capabilities/registry.py+++ b/deeptutor/capabilities/registry.py@@ -13,6 +13,7 @@ import warningsfrom deeptutor.capabilities.protocol import LoopExtensionfrom deeptutor.core.context import UnifiedContext+from deeptutor.modules.catalog import contribution_enabled, manifestsfrom deeptutor.plugins.entry_points import load_entry_point_groupfrom deeptutor.runtime.capability_catalog import EmptyConfig, get_capability_catalog@@ -46,45 +47,10 @@ class LoopCapabilitySpec:return self.create()-BUILTIN_LOOP_CAPABILITY_SPECS: tuple[LoopCapabilitySpec, ...] = (- LoopCapabilitySpec(- "ask_questions",- "deeptutor.capabilities.ask_questions.loop:AskQuestionsLoopCapability",- ),- LoopCapabilitySpec("mastery", "deeptutor.capabilities.mastery.loop:MasteryLoopCapability"),- LoopCapabilitySpec("solve", "deeptutor.capabilities.solve.loop:SolveLoopCapability"),- LoopCapabilitySpec("notes", "deeptutor.capabilities.notes.capability:NotesCapability"),- LoopCapabilitySpec("obsidian", "deeptutor.capabilities.obsidian.capability:ObsidianCapability"),- LoopCapabilitySpec(- "marginnote4",- "deeptutor.capabilities.marginnote4.capability:MarginNoteCapability",- ),- LoopCapabilitySpec(- "subagent",- "deeptutor.capabilities.subagent.capability:SubagentCapability",- ),- LoopCapabilitySpec("ima", "deeptutor.capabilities.ima.capability:ImaCapability"),- LoopCapabilitySpec(- "immersive_reading",- "deeptutor.capabilities.reading.capability:ReadingCapability",- ),- LoopCapabilitySpec(- "explore_context",- "deeptutor.capabilities.explore_context.capability:ExploreContextCapability",- ),- LoopCapabilitySpec("setup", "deeptutor.capabilities.setup.capability:SetupCapability"),- LoopCapabilitySpec(- "partner_authoring",- "deeptutor.capabilities.partner_authoring.capability:PartnerAuthoringCapability",- ),- LoopCapabilitySpec(- "partner_group",- "deeptutor.capabilities.partner_group.capability:PartnerGroupCapability",- ),- LoopCapabilitySpec(- "visualization_generation",- "deeptutor.visualizers.loop_capability:VisualizationLoopCapability",- ),+BUILTIN_LOOP_CAPABILITY_SPECS: tuple[LoopCapabilitySpec, ...] = tuple(+ LoopCapabilitySpec(name, spec["class_path"])+ for module in manifests().values()+ for name, spec in module["loops"].items())# Compatibility surface: the descriptors remain zero-argument callables.@@ -94,14 +60,18 @@ LOOP_EXTENSION_FACTORIES: tuple[LoopFactory, ...] = cast(def _builtin_loop_extensions() -> tuple[LoopExtension, ...]:- return tuple(factory() for factory in LOOP_EXTENSION_FACTORIES)+ return tuple(+ spec() for spec in BUILTIN_LOOP_CAPABILITY_SPECS if contribution_enabled("loops", spec.name)+ )class _LegacyLoopCapabilitiesView(Sequence[LoopExtension]):"""Deprecated sequence view that never retains extension instances."""def __len__(self) -> int:- return len(LOOP_EXTENSION_FACTORIES)+ return sum(+ contribution_enabled("loops", spec.name) for spec in BUILTIN_LOOP_CAPABILITY_SPECS+ )def __iter__(self) -> Iterator[LoopExtension]:return iter(_builtin_loop_extensions())@@ -186,34 +156,41 @@ def discover_external_loop_capabilities():discover_external_loop_capabilities.cache_clear = _discover_external_loop_capabilities.cache_clear # type: ignore[attr-defined]-def _register_loop_entry(name: str, factory: LoopFactory) -> None:- preview = factory()- get_capability_catalog().register(- name=name,- kind="loop_extension",- manifest={"name": name, "owned_tools": tuple(preview.owned_tools)},- factory=factory,- config_model=EmptyConfig,- replace=True,- )---def all_loop_capabilities() -> tuple[LoopExtension, ...]:- """Create an isolated extension set for the caller's turn."""-- specs: list[tuple[str, LoopFactory]] = []- specs.extend((spec.name, spec) for spec in BUILTIN_LOOP_CAPABILITY_SPECS)+def all_loop_capabilities(context: UnifiedContext | None = None) -> tuple[LoopExtension, ...]:+ """Create once per turn, rechecking activation and revocation on each use."""+ specs: list[tuple[str, LoopFactory]] = [+ (spec.name, spec)+ for spec in BUILTIN_LOOP_CAPABILITY_SPECS+ if contribution_enabled("loops", spec.name)+ ]specs.extend(discover_external_loop_capabilities())+ instances = context.runtime.loop_extensions if context is not None else {}+ allowed = {name for name, _ in specs}+ for name in tuple(instances):+ if name not in allowed:+ del instances[name]+ result = []for name, factory in specs:- _register_loop_entry(name, factory)- catalog = get_capability_catalog()- return tuple(- cast(LoopExtension, catalog.create("loop_extension", name)) for name, _factory in specs- )+ instance = instances.get(name)+ if instance is None:+ instance = factory()+ instances[name] = instance+ get_capability_catalog().register(+ name=name,+ kind="loop_extension",+ manifest={"name": name, "owned_tools": tuple(instance.owned_tools)},+ factory=factory,+ config_model=EmptyConfig,+ replace=True,+ )+ result.append(cast(LoopExtension, instance))+ return tuple(result)def active_loop_capabilities(context: UnifiedContext) -> tuple[LoopExtension, ...]:- return tuple(extension for extension in all_loop_capabilities() if extension.is_active(context))+ return tuple(+ extension for extension in all_loop_capabilities(context) if extension.is_active(context)+ )def any_exclusive_capability_active(context: UnifiedContext) -> bool:diff --git a/deeptutor/capabilities/setup/access.py b/deeptutor/capabilities/setup/access.pyindex c66e93173..d5575def3 100644--- a/deeptutor/capabilities/setup/access.py+++ b/deeptutor/capabilities/setup/access.py@@ -45,8 +45,8 @@ class AccessDecision:def _is_partner_turn() -> bool:try:+ from deeptutor.core.identities import is_partner_user_idfrom deeptutor.multi_user.context import get_current_user- from deeptutor.services.partners.scope import is_partner_user_idreturn bool(is_partner_user_id(get_current_user().id))except Exception: # noqa: BLE001 - no multi-user layer configureddiff --git a/deeptutor/capabilities/solve/capability.py b/deeptutor/capabilities/solve/capability.pyindex 506c6224e..74845dc14 100644--- a/deeptutor/capabilities/solve/capability.py+++ b/deeptutor/capabilities/solve/capability.py@@ -24,14 +24,12 @@ from typing import castfrom deeptutor.agents.chat.agentic_pipeline import AgenticChatPipelinefrom deeptutor.capabilities.solve.session import DEFAULT_MAX_REPLANS-from deeptutor.capabilities.solve.tools import SOLVE_TOOL_NAMESfrom deeptutor.core.capability_protocol import (- CapabilityManifest,StreamBusProtocol,TurnCapability,)from deeptutor.core.context import UnifiedContext-from deeptutor.runtime.request_contracts import get_capability_request_schema+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifestfrom deeptutor.runtime.stream_bus import StreamBusfrom deeptutor.services.config.capabilities_settings import get_solve_params@@ -62,14 +60,7 @@ def resolve_solve_session_id(context: UnifiedContext) -> str:class DeepSolveCapability(TurnCapability):- manifest = CapabilityManifest(- name="deep_solve",- description="Multi-step problem solving driven by the chat agent loop.",- stages=["responding"],- tools_used=[*SOLVE_TOOL_NAMES, "rag", "exec", "geogebra_analysis", "reason"],- cli_aliases=["solve"],- request_schema=get_capability_request_schema("deep_solve"),- )+ manifest = builtin_capability_manifest("deep_solve")async def run(self, context: UnifiedContext, stream: StreamBusProtocol) -> None:context.metadata["solve_mode"] = Truediff --git a/deeptutor/capabilities/subagent/binding.py b/deeptutor/capabilities/subagent/binding.pyindex bc8d45691..d85ea0cdc 100644--- a/deeptutor/capabilities/subagent/binding.py+++ b/deeptutor/capabilities/subagent/binding.py@@ -46,8 +46,6 @@ def _resolve(context: UnifiedContext) -> dict[str, str] | None:"cwd": "",}- from deeptutor.multi_user.knowledge_access import resolve_kb_metadata-partner_id = str(context.runtime.consult_partner_id or "").strip()if partner_id:from deeptutor.multi_user.partner_access import visible_partner_cards@@ -60,6 +58,10 @@ def _resolve(context: UnifiedContext) -> dict[str, str] | None:"cwd": "",}+ if not context.knowledge_bases:+ return None+ from deeptutor.multi_user.knowledge_access import resolve_kb_metadata+for ref in context.knowledge_bases or []:ref = str(ref).strip()if not ref:diff --git a/deeptutor/core/context.py b/deeptutor/core/context.pyindex 90954eb6c..cc0e77e16 100644--- a/deeptutor/core/context.py+++ b/deeptutor/core/context.py@@ -51,6 +51,7 @@ class WorkspaceRuntimeContext:class TurnRuntimeContext:"""Non-serializable execution state owned by the runtime adapter."""+ loop_extensions: dict[str, Any] = field(default_factory=dict, repr=False)turn_id: str = ""wait_for_user_reply: Callable[[], Awaitable[dict[str, Any] | None]] | None = None# Takes the messages the learner sent while this turn was runningdiff --git a/deeptutor/core/errors.py b/deeptutor/core/errors.pyindex 3db1489c2..7a9676356 100644--- a/deeptutor/core/errors.py+++ b/deeptutor/core/errors.py@@ -55,3 +55,12 @@ class EnvironmentConfigError(ConfigurationError):"""Raised when there's an environment-related configuration error."""pass+++class AccessError(DeepTutorError):+ """Transport-independent access failure, translated by HTTP adapters."""++ def __init__(self, status_code: int, detail: str):+ super().__init__(detail)+ self.status_code = status_code+ self.detail = detaildiff --git a/deeptutor/core/identities.py b/deeptutor/core/identities.pynew file mode 100644index 000000000..e1ccbecfd--- /dev/null+++ b/deeptutor/core/identities.py@@ -0,0 +1,11 @@+"""Stable identity grammar shared by the host and channel adapters."""++PARTNER_USER_PREFIX = "partner_"+++def partner_user_id(partner_id: str) -> str:+ return f"{PARTNER_USER_PREFIX}{partner_id}"+++def is_partner_user_id(user_id: str) -> bool:+ return user_id.startswith(PARTNER_USER_PREFIX)diff --git a/deeptutor/core/source_context.py b/deeptutor/core/source_context.pynew file mode 100644index 000000000..a49294341--- /dev/null+++ b/deeptutor/core/source_context.py@@ -0,0 +1,11 @@+"""Serialized context contributed by an optional content application."""++from dataclasses import dataclass, field+from typing import Any+++@dataclass+class SourceContext:+ text: str = ""+ references: list[dict[str, Any]] = field(default_factory=list)+ warnings: list[str] = field(default_factory=list)diff --git a/deeptutor/knowledge/add_documents.py b/deeptutor/knowledge/add_documents.pyindex 3832be829..343a4f5d3 100644--- a/deeptutor/knowledge/add_documents.py+++ b/deeptutor/knowledge/add_documents.py@@ -23,7 +23,6 @@ from deeptutor.services.rag.factory import (has_ready_provider_index,normalize_provider_name,)-from deeptutor.services.rag.file_routing import FileTypeRouterfrom deeptutor.services.rag.index_probe import provider_failure_summaryfrom deeptutor.services.rag.index_versioning import list_kb_versionsfrom deeptutor.services.rag.provider_binding import resolve_bound_provider@@ -33,6 +32,7 @@ from deeptutor.services.setup.data_volume import (ensure_data_volume_writable,format_data_volume_permission_error,)+from deeptutor.utils.file_types import FileTypeRouterlogger = logging.getLogger(__name__)diff --git a/deeptutor/knowledge/indexing_run.py b/deeptutor/knowledge/indexing_run.pyindex 8a3a73774..71131426b 100644--- a/deeptutor/knowledge/indexing_run.py+++ b/deeptutor/knowledge/indexing_run.py@@ -8,12 +8,10 @@ queue or a second parsing cache.from __future__ import annotationsimport asyncio-from contextvars import ContextVarfrom hashlib import sha256import jsonimport osfrom pathlib import Path-import reimport sysimport threadingimport time@@ -26,8 +24,22 @@ except ImportError: # CLI-only installs need no process-monitor dependency.psutil = Nonefrom deeptutor.services.file_io import atomic_write_json, read_text+from deeptutor.services.parsing.progress import (+ _CURRENT,+)+from deeptutor.services.parsing.progress import (+ IndexingCancelled as IndexingCancelled,+)+from deeptutor.services.parsing.progress import (+ _redact as _redact,+)+from deeptutor.services.parsing.progress import (+ current_run as current_run,+)+from deeptutor.services.parsing.progress import (+ failure_code as failure_code,+)-_CURRENT: ContextVar[IndexingRun | None] = ContextVar("indexing_run", default=None)_TERMINAL = {"completed", "partial", "failed", "cancelled", "interrupted"}_RECOVERY_DESCRIPTION = ("Retry reuses validated parser outputs and completed cloud-parsing slices. "@@ -39,53 +51,6 @@ class IndexingBusyError(RuntimeError):pass-class IndexingCancelled(RuntimeError):- pass---def current_run() -> IndexingRun | None:- return _CURRENT.get()---def _redact(detail: str) -> str:- text = re.sub(r"(?i)(bearer\s+)[^\s]+", r"\1[redacted]", str(detail))- text = re.sub(- r"(?i)((?:api[_-]?key|token|secret|password|signature|authorization)\s*[=:]\s*)[^\s&]+",- r"\1[redacted]",- text,- )- text = re.sub(- r'(?i)(["\']?(?:api[_-]?key|token|secret|password|signature|authorization)["\']?\s*[:=]\s*)["\'][^"\']*["\']',- r'\1"[redacted]"',- text,- )- text = re.sub(r"(https?://)[^/\s@]+:[^/\s@]+@", r"\1[redacted]@", text)- return text[-1600:]---def failure_code(exc: BaseException) -> str:- text = str(exc).casefold()- if isinstance(exc, (TimeoutError,)) or "timeout" in text or "timed out" in text:- return "timeout"- if isinstance(exc, MemoryError) or "out of memory" in text or "resource exhausted" in text:- return "resource_exhaustion"- if (- isinstance(exc, (FileNotFoundError, ModuleNotFoundError))- or "not installed" in text- or "cli_missing" in text- ):- return "dependency_missing"- if "unsupported" in text or "doesn't support" in text:- return "unsupported_input"- if "download" in text:- return "model_download_failed"- if "embedding" in text or "vector" in text:- return "embedding_failed"- if "no content" in text or "no output" in text or "invalid" in text:- return "invalid_output"- return "runtime_failure"--def load_run(kb_dir: Path) -> dict[str, Any] | None:path = Path(kb_dir) / ".indexing-run.json"try:@@ -255,7 +220,7 @@ class IndexingRun:"cancel_requested": False,"usable_version": None,}- from deeptutor.services.rag.file_routing import FileTypeRouter+ from deeptutor.utils.file_types import FileTypeRoutercandidates = list(dict.fromkeys(self.sources))raw = self.kb_dir / "raw"diff --git a/deeptutor/knowledge/initializer.py b/deeptutor/knowledge/initializer.pyindex 364bd2ba3..cb4fb367f 100644--- a/deeptutor/knowledge/initializer.py+++ b/deeptutor/knowledge/initializer.py@@ -21,13 +21,13 @@ from deeptutor.knowledge.progress_tracker import ProgressStage, ProgressTrackerfrom deeptutor.services.config import resolve_llm_runtime_configfrom deeptutor.services.file_io import atomic_write_jsonfrom deeptutor.services.rag.factory import normalize_provider_name-from deeptutor.services.rag.file_routing import FileTypeRouterfrom deeptutor.services.rag.service import RAGServicefrom deeptutor.services.setup.data_volume import (DataVolumePermissionError,ensure_data_volume_writable,format_data_volume_permission_error,)+from deeptutor.utils.file_types import FileTypeRouterlogger = logging.getLogger(__name__)diff --git a/deeptutor/knowledge/manager.py b/deeptutor/knowledge/manager.pyindex 3bef8686a..39241853d 100644--- a/deeptutor/knowledge/manager.py+++ b/deeptutor/knowledge/manager.py@@ -48,13 +48,13 @@ from deeptutor.services.rag.factory import (normalize_provider_name,provider_uses_embedding_versions,)-from deeptutor.services.rag.file_routing import FileTypeRouterfrom deeptutor.services.rag.index_probe import (inspect_kb_versions,inspect_provider_version,provider_failure_summary,)from deeptutor.services.web_source.crawler import MAX_CRAWL_DEPTH, MAX_CRAWL_PAGES+from deeptutor.utils.file_types import FileTypeRouterlogger = logging.getLogger(__name__)diff --git a/deeptutor/knowledge/module_service.py b/deeptutor/knowledge/module_service.pynew file mode 100644index 000000000..e22e386f2--- /dev/null+++ b/deeptutor/knowledge/module_service.py@@ -0,0 +1,29 @@+"""Background services contributed by this installed module."""+++async def start_github_sync(application_container) -> None:+ from deeptutor.services.github_source.sync_service import get_sync_service++ await get_sync_service().start()+++async def stop_github_sync(application_container) -> None:+ from deeptutor.services.github_source.sync_service import get_sync_service++ await get_sync_service().stop()+++async def start_web_source_sync(application_container) -> None:+ from deeptutor.services.web_source.scheduler import (+ start_web_source_sync_scheduler,+ )++ await start_web_source_sync_scheduler()+++async def stop_web_source_sync(application_container) -> None:+ from deeptutor.services.web_source.scheduler import (+ stop_web_source_sync_scheduler,+ )++ await stop_web_source_sync_scheduler()diff --git a/deeptutor/learning/topic_materials.py b/deeptutor/learning/topic_materials.pyindex e35af23b9..ad5ad6fa2 100644--- a/deeptutor/learning/topic_materials.py+++ b/deeptutor/learning/topic_materials.py@@ -105,6 +105,9 @@ def _load_book_materials(source_id: str, label: str, budget: int) -> list[TopicMthe reason — because "this chapter exists but has not been written" issomething the tutor must be able to say instead of inventing its contents."""+ from deeptutor.modules.catalog import require_module++ require_module("books")from deeptutor.book.context import build_book_contextfrom deeptutor.book.storage import get_book_storage@@ -199,6 +202,9 @@ def _load_book_materials(source_id: str, label: str, budget: int) -> list[TopicMdef _load_notebook_material(source_id: str, label: str, budget: int) -> TopicMaterial:"""A notebook stays one material: its records are already record-sized."""+ from deeptutor.modules.catalog import require_module++ require_module("notebook")from deeptutor.services.notebook import get_notebook_managerrecords = get_notebook_manager().get_records_by_references(@@ -345,6 +351,9 @@ def _load_question_bank_material(source_id: str, label: str, budget: int) -> Topdef _load_cowriter_material(source_id: str, label: str, budget: int) -> TopicMaterial:"""One Co-Writer draft, read as the learner's own writing on the subject."""+ from deeptutor.modules.catalog import require_module++ require_module("co-writer")from deeptutor.co_writer.storage import get_co_writer_storagedocument = get_co_writer_storage().load_document(source_id)diff --git a/deeptutor/modules/__init__.py b/deeptutor/modules/__init__.pynew file mode 100644index 000000000..ec7356be9--- /dev/null+++ b/deeptutor/modules/__init__.py@@ -0,0 +1,5 @@+"""Import-free module discovery and deployment-scoped feature selection."""++from .catalog import ModuleUnavailable, module_enabled, module_for_path, module_statuses++__all__ = ["ModuleUnavailable", "module_enabled", "module_for_path", "module_statuses"]diff --git a/deeptutor/modules/catalog.py b/deeptutor/modules/catalog.pynew file mode 100644index 000000000..fc21469ad--- /dev/null+++ b/deeptutor/modules/catalog.py@@ -0,0 +1,246 @@+"""The module manifest is shared by packaging, runtime assembly and clients.++Reading the catalog never imports a feature or creates its services. Package+ownership is distinct from deployment selection and from execution readiness.+User authorization remains the responsibility of existing scoped adapters.+"""++from __future__ import annotations++from functools import cache+from importlib import metadata+import json+from pathlib import Path+import shutil+from typing import Any++from packaging.requirements import Requirement+++class ModuleUnavailable(ValueError):+ pass+++@cache+def manifests() -> dict[str, dict[str, Any]]:+ result = {}+ for path in sorted(Path(__file__).with_name("manifests").glob("*.json")):+ row = json.loads(path.read_text(encoding="utf-8"))+ if row["schema_version"] != 1 or row["id"] != path.stem:+ raise ValueError(f"Invalid module manifest: {path.name}")+ result[row["id"]] = row+ owners: dict[tuple[str, str], str] = {}+ for name, row in result.items():+ for dependency in [*row["requires"], *row["optional"]]:+ if dependency not in result or dependency == name:+ raise ValueError(f"Invalid module dependency: {name} -> {dependency}")+ for kind in ("tools", "capabilities", "loops"):+ for spec in row[kind].values():+ for dependency in spec.get("requires", []):+ if dependency not in {*row["requires"], *row["optional"]}:+ raise ValueError(+ f"Undeclared contribution dependency: {name} -> {dependency}"+ )+ for kind in ("capabilities", "loops", "tools", "paths"):+ for key in row[kind]:+ identity = (kind, key)+ if identity in owners:+ raise ValueError(+ f"Duplicate {kind} owner for {key}: {owners[identity]}, {name}"+ )+ owners[identity] = name+ for prefix in row["paths"]:+ if prefix.startswith("/") or ".." in prefix.split("/"):+ raise ValueError(f"Invalid module path: {prefix}")+ for route in row["routes"]:+ if route["auth"] not in {"public", "authenticated", "learning", "admin"}:+ raise ValueError(f"Invalid route authorization policy: {name}")+ visiting: set[str] = set()+ visited: set[str] = set()++ def visit(name: str) -> None:+ if name in visiting:+ raise ValueError(f"Cyclic module dependency: {name}")+ if name in visited:+ return+ if name not in result:+ raise ValueError(f"Unknown required module: {name}")+ visiting.add(name)+ for dependency in result[name]["requires"]:+ visit(dependency)+ visiting.remove(name)+ visited.add(name)++ for name in result:+ visit(name)+ return result+++@cache+def source_checkout() -> bool:+ root = Path(__file__).resolve().parents[2]+ return (root / ".git").exists() and (root / "pyproject.toml").is_file()+++def state_path() -> Path:+ from deeptutor.runtime.home import get_runtime_data_root++ return get_runtime_data_root() / "system" / "modules.json"+++def selection() -> dict[str, bool]:+ path = state_path()+ if not path.exists():+ return {}+ raw = json.loads(path.read_text(encoding="utf-8"))+ if raw.get("schema_version") != 1 or not isinstance(raw.get("enabled"), dict):+ raise ValueError(f"Invalid module state: {path}")+ enabled = raw["enabled"]+ if any(name not in manifests() or type(value) is not bool for name, value in enabled.items()):+ raise ValueError(f"Invalid module selection: {path}")+ return enabled+++def installed(name: str) -> bool:+ if name == "core":+ return True+ if source_checkout():+ return True+ try:+ metadata.distribution(manifests()[name]["distribution"])+ return True+ except metadata.PackageNotFoundError:+ return False+++def module_enabled(name: str, *, selected: dict[str, bool] | None = None) -> bool:+ if name not in manifests():+ raise ValueError(f"Unknown module: {name}")+ if name == "core":+ return True+ selected = selection() if selected is None else selected+ if not installed(name) or not selected.get(name, True):+ return False+ if not source_checkout():+ from deeptutor.__version__ import __version__++ if metadata.version(manifests()[name]["distribution"]) != __version__:+ return False+ return all(module_enabled(dep, selected=selected) for dep in manifests()[name]["requires"])+++def require_module(name: str) -> None:+ if not module_enabled(name):+ raise ModuleUnavailable(+ f"Module '{name}' is unavailable. Run `deeptutor module install {name}` "+ f"and `deeptutor module enable {name}`."+ )+++@cache+def module_for_path(path: str) -> str:+ """Longest explicit path owns the file; unassigned shared code is core."""+ path = path.replace("\\", "/")+ candidates = [+ (len(prefix), name)+ for name, row in manifests().items()+ for prefix in row["paths"]+ if path == prefix or path.startswith(prefix + "/")+ ]+ return max(candidates)[1] if candidates else "core"+++def contribution_owner(kind: str, name: str) -> str:+ for module, row in manifests().items():+ if name in row[kind]:+ return module+ return "core"+++def contribution_enabled(kind: str, name: str) -> bool:+ owner = contribution_owner(kind, name)+ spec = manifests()[owner][kind].get(name, {})+ return module_enabled(owner) and all(+ module_enabled(dependency) for dependency in spec.get("requires", [])+ )+++def dependency_order(names: list[str]) -> list[str]:+ ordered: list[str] = []++ def visit(name: str) -> None:+ if name not in manifests():+ raise ValueError(f"Unknown module: {name}")+ if name in ordered:+ return+ for dependency in manifests()[name]["requires"]:+ visit(dependency)+ ordered.append(name)++ for name in names:+ visit(name)+ return ordered+++def dependents(name: str, *, enabled_only: bool = False) -> list[str]:+ return [+ key+ for key in manifests()+ if key != name+ and name in dependency_order([key])+ and (module_enabled(key) if enabled_only else installed(key))+ ]+++def module_statuses() -> list[dict[str, Any]]:+ from deeptutor.__version__ import __version__++ selected = selection()+ rows = []+ for name, manifest in manifests().items():+ present = installed(name)+ enabled = module_enabled(name, selected=selected)+ issues = []+ for dependency in manifest["requires"]:+ if not module_enabled(dependency, selected=selected):+ issues.append(f"Required module unavailable: {dependency}")+ if present:+ if not source_checkout() and name != "core":+ version = metadata.version(manifest["distribution"])+ if version != __version__:+ issues.append(f"Module version {version} must match core {__version__}")+ for raw in manifest["requirements"]:+ requirement = Requirement(raw)+ if requirement.marker and not requirement.marker.evaluate():+ continue+ try:+ version = metadata.version(requirement.name)+ if version not in requirement.specifier:+ issues.append(f"Requires {raw}; installed {version}")+ except metadata.PackageNotFoundError:+ issues.append(f"Missing package: {raw}")+ for executable in manifest["executables"]:+ if shutil.which(executable) is None:+ issues.append(f"Missing executable: {executable}")+ rows.append(+ {+ "id": name,+ "distribution": manifest["distribution"],+ "installed": present,+ "enabled": enabled,+ "ready": enabled and not issues,+ "issues": issues,+ "requires": manifest["requires"],+ "navigation": manifest["navigation"],+ "capabilities": list(manifest["capabilities"]),+ "source": source_checkout(),+ }+ )+ by_id = {row["id"]: row for row in rows}+ for name in dependency_order(list(by_id)):+ row = by_id[name]+ for dependency in row["requires"]:+ if by_id[dependency]["enabled"] and not by_id[dependency]["ready"]:+ row["issues"].append(f"Required module not ready: {dependency}")+ row["ready"] = False+ return rowsdiff --git a/deeptutor/modules/lifecycle.py b/deeptutor/modules/lifecycle.pynew file mode 100644index 000000000..46dc4a97d--- /dev/null+++ b/deeptutor/modules/lifecycle.py@@ -0,0 +1,281 @@+"""Offline module changes: dependency planning, environment leases and pip.++Official wheels share the host interpreter. Mutations require exclusive+ownership of that environment; serving processes and turns hold read leases.+Removing code never removes user data or uninstalls transitive packages.+"""++from __future__ import annotations++from contextlib import ExitStack, contextmanager+import hashlib+from importlib import metadata+import json+import os+from pathlib import Path+import subprocess+import sys+import tempfile++from .catalog import (+ dependency_order,+ dependents,+ installed,+ manifests,+ selection,+ source_checkout,+ state_path,+)+++class ModuleLifecycleError(ValueError):+ pass+++@contextmanager+def environment_lease(*, exclusive: bool = False):+ # Deployments may share a home across interpreters. Lock both package files+ # and module selection so another environment cannot disable a live feature.+ identities = (str(Path(sys.prefix).resolve()), str(state_path().resolve()))+ with ExitStack() as stack:+ for identity in identities:+ stack.enter_context(_file_lease(identity, exclusive=exclusive))+ yield+++@contextmanager+def _file_lease(identity: str, *, exclusive: bool):+ identity = hashlib.sha256(identity.encode()).hexdigest()[:24]+ path = Path(tempfile.gettempdir()) / f"deeptutor-environment-{identity}.lock"+ with path.open("a+b") as handle:+ if sys.platform == "win32":+ import ctypes+ from ctypes import wintypes+ import msvcrt++ class Overlapped(ctypes.Structure):+ _fields_ = [+ ("Internal", ctypes.c_size_t),+ ("InternalHigh", ctypes.c_size_t),+ ("Offset", wintypes.DWORD),+ ("OffsetHigh", wintypes.DWORD),+ ("hEvent", wintypes.HANDLE),+ ]++ kernel = ctypes.WinDLL("kernel32", use_last_error=True)+ overlapped = Overlapped()+ native = wintypes.HANDLE(msvcrt.get_osfhandle(handle.fileno()))+ if not kernel.LockFileEx(+ native, 1 | (2 if exclusive else 0), 0, 1, 0, ctypes.byref(overlapped)+ ):+ raise ModuleLifecycleError(+ "Environment is in use. Stop DeepTutor before changing modules."+ )+ try:+ yield+ finally:+ kernel.UnlockFileEx(native, 0, 1, 0, ctypes.byref(overlapped))+ else:+ import fcntl++ try:+ fcntl.flock(handle, (fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH) | fcntl.LOCK_NB)+ except BlockingIOError as exc:+ raise ModuleLifecycleError(+ "Environment is in use. Stop DeepTutor before changing modules."+ ) from exc+ try:+ yield+ finally:+ fcntl.flock(handle, fcntl.LOCK_UN)+++def plan(action: str, name: str) -> dict:+ if name not in manifests():+ raise ModuleLifecycleError(f"Unknown module: {name}")+ if name == "core" and action in {"disable", "uninstall"}:+ raise ModuleLifecycleError("The core module cannot be removed or disabled.")+ if action not in {"install", "uninstall", "enable", "disable"}:+ raise ModuleLifecycleError(f"Unknown action: {action}")+ affected = dependency_order([name]) if action in {"install", "enable"} else [name]+ blockers = (+ dependents(name, enabled_only=action == "disable")+ if action in {"disable", "uninstall"}+ else []+ )+ if action == "uninstall" and not source_checkout():+ from packaging.requirements import Requirement++ target = _canonical(manifests()[name]["distribution"])+ for distribution in metadata.distributions():+ package = distribution.metadata.get("Name", "")+ if _canonical(package) == target:+ continue+ for raw in distribution.requires or ():+ requirement = Requirement(raw)+ if (requirement.marker is None or requirement.marker.evaluate()) and _canonical(+ requirement.name+ ) == target:+ # Include dependents outside the official catalog as well.+ if package not in {+ manifests()[key]["distribution"] if key in manifests() else key+ for key in blockers+ }:+ blockers.append(package)+ break+ return {+ "action": action,+ "module": name,+ "affected": affected,+ "blocked_by": blockers,+ "preserves_data": True,+ "requires_stopped_environment": True,+ }+++def _save_selection(enabled: dict[str, bool]) -> None:+ path = state_path()+ path.parent.mkdir(parents=True, exist_ok=True)+ fd, temporary = tempfile.mkstemp(prefix=".modules-", dir=path.parent)+ try:+ with os.fdopen(fd, "w", encoding="utf-8") as stream:+ json.dump({"schema_version": 1, "enabled": enabled}, stream, indent=2)+ stream.write("\n")+ stream.flush()+ os.fsync(stream.fileno())+ os.replace(temporary, path)+ finally:+ Path(temporary).unlink(missing_ok=True)+++def change(action: str, name: str, *, wheelhouse: Path | None = None) -> dict:+ from deeptutor.__version__ import __version__++ with environment_lease(exclusive=True):+ # Refuse malformed state before any package mutation, including uninstall.+ enabled = selection()+ result = plan(action, name)+ if result["blocked_by"]:+ raise ModuleLifecycleError("Required by: " + ", ".join(result["blocked_by"]))+ if action in {"enable", "disable"}:+ for module in result["affected"]:+ if action == "enable" and not installed(module):+ raise ModuleLifecycleError(f"Install {module} before enabling it.")+ if action == "enable" and not source_checkout() and module != "core":+ version = metadata.version(manifests()[module]["distribution"])+ if version != __version__:+ raise ModuleLifecycleError(+ f"Module {module} version {version} must match core {__version__}."+ )+ enabled[module] = action == "enable"+ _save_selection(enabled)+ return result+ if source_checkout():+ raise ModuleLifecycleError(+ "This is a source checkout. Use enable/disable here; install/uninstall "+ "operates on wheel installations in a separate virtual environment."+ )+ base = [sys.executable, "-m", "pip", "--disable-pip-version-check"]+ if action == "install":+ targets = [+ f"{manifests()[module]['distribution']}=={__version__}"+ for module in result["affected"]+ if module != "core"+ ]+ targets.append(f"deeptutor=={__version__}")+ before = {+ _canonical(dist.metadata["Name"]): dist.version+ for dist in metadata.distributions()+ if dist.metadata["Name"]+ }+ with tempfile.TemporaryDirectory(prefix="deeptutor-install-") as directory:+ stage = Path(directory)+ report = stage / "plan.json"+ source = ["--find-links", str(wheelhouse.resolve())] if wheelhouse else []+ _pip([*base, "install", "--dry-run", "--report", str(report), *source, *targets])+ resolved = json.loads(report.read_text())["install"]+ replacements = [+ row["metadata"]["name"]+ for row in resolved+ if _canonical(row["metadata"]["name"]) in before+ and before[_canonical(row["metadata"]["name"])] != row["metadata"]["version"]+ ]+ if replacements:+ raise ModuleLifecycleError(+ "Installation would replace existing dependencies: "+ + ", ".join(replacements)+ + ". Use a fresh virtual environment or update the whole environment explicitly."+ )+ # Build precisely the dry-run solution. Resolving again could select+ # different versions, or rebuild dependencies already installed.+ artifacts = []+ for row in resolved:+ info = row["download_info"]+ url = info["url"]+ digest = info.get("archive_info", {}).get("hashes", {}).get("sha256")+ if digest and "#" not in url:+ url += "#sha256=" + digest+ artifacts.append(url)+ if artifacts:+ _pip([*base, "wheel", "--no-deps", "--wheel-dir", str(stage), *artifacts])+ try:+ wheels = sorted(str(path) for path in stage.glob("*.whl"))+ log = (+ _pip([*base, "install", "--no-deps", "--no-index", *wheels])+ if wheels+ else "Requested modules are already installed."+ )+ for module in result["affected"]:+ enabled[module] = True+ _save_selection(enabled)+ except BaseException:+ added = sorted(+ {+ _canonical(dist.metadata["Name"])+ for dist in metadata.distributions()+ if dist.metadata["Name"]+ }+ - before.keys()+ )+ if added:+ _pip([*base, "uninstall", "-y", *added])+ raise+ return {**result, "log": log}+ else:+ log = _pip([*base, "uninstall", "-y", manifests()[name]["distribution"]])+ # Selection changes only after pip succeeds. Dependencies are never+ # auto-removed: other applications may also own them in this interpreter.+ enabled.pop(name, None)+ _save_selection(enabled)+ return {**result, "log": log}+++def _canonical(name: str) -> str:+ from packaging.utils import canonicalize_name++ return canonicalize_name(name)+++def _pip(argv: list[str]) -> str:+ """Do not release the environment lease while pip/build children still run."""+ try:+ process = subprocess.Popen(+ argv,+ stdout=subprocess.PIPE,+ stderr=subprocess.PIPE,+ text=True,+ start_new_session=os.name != "nt",+ )+ try:+ stdout, stderr = process.communicate(timeout=900)+ except BaseException:+ from deeptutor.runtime.process import kill_process_tree++ kill_process_tree(process.pid)+ process.communicate()+ raise+ except OSError as exc:+ raise ModuleLifecycleError(str(exc)) from exc+ if process.returncode:+ raise ModuleLifecycleError((stderr or stdout)[-6000:])+ return stdoutdiff --git a/deeptutor/modules/manifests/audio-overview.json b/deeptutor/modules/manifests/audio-overview.jsonnew file mode 100644index 000000000..0246b4d76--- /dev/null+++ b/deeptutor/modules/manifests/audio-overview.json@@ -0,0 +1,53 @@+{+ "schema_version": 1,+ "id": "audio-overview",+ "distribution": "deeptutor-audio-overview",+ "requires": [+ "knowledge"+ ],+ "optional": [+ "co-writer"+ ],+ "paths": [+ "deeptutor/capabilities/audio_overview"+ ],+ "capabilities": {+ "audio_overview": {+ "class_path": "deeptutor.capabilities.audio_overview.capability:AudioOverviewCapability",+ "config_model": "deeptutor.capabilities.audio_overview.request_config:AudioOverviewRequestConfig",+ "manifest": {+ "name": "audio_overview",+ "description": "Create a grounded two-voice audio overview and transcript from a knowledge base.",+ "stages": [+ "retrieving",+ "script_writing",+ "voice_generation",+ "publishing"+ ],+ "tools_used": [+ "rag"+ ],+ "cli_aliases": [+ "audio-overview",+ "overview"+ ],+ "config_defaults": {+ "topic": "",+ "target_minutes": 5,+ "host_voice": null,+ "expert_voice": null,+ "max_context_chunks": 6+ }+ },+ "order": 10+ }+ },+ "loops": {},+ "tools": {},+ "routes": [],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [],+ "executables": []+}diff --git a/deeptutor/modules/manifests/books.json b/deeptutor/modules/manifests/books.jsonnew file mode 100644index 000000000..577b8bd46--- /dev/null+++ b/deeptutor/modules/manifests/books.json@@ -0,0 +1,66 @@+{+ "schema_version": 1,+ "id": "books",+ "distribution": "deeptutor-books",+ "requires": [+ "knowledge",+ "parsing",+ "questions",+ "visualize",+ "mastery"+ ],+ "optional": [+ "notebook",+ "renderer-manim"+ ],+ "paths": [+ "deeptutor/book",+ "deeptutor_cli/book.py",+ "deeptutor/api/routers/book.py",+ "deeptutor/multi_user/book_access.py"+ ],+ "capabilities": {},+ "loops": {},+ "tools": {},+ "routes": [+ {+ "reference": "deeptutor.api.routers.book:router",+ "options": {+ "prefix": "/api",+ "tags": [+ "books"+ ]+ },+ "auth": "learning",+ "order": 646+ },+ {+ "reference": "deeptutor.api.routers.book:ws_router",+ "options": {+ "prefix": "/ws",+ "tags": [+ "books"+ ]+ },+ "auth": "public",+ "order": 649+ }+ ],+ "commands": [+ {+ "name": "book",+ "register": "deeptutor_cli.book:register",+ "help": "Manage book."+ }+ ],+ "navigation": [+ "/books",+ "/learning/books"+ ],+ "services": [],+ "requirements": [],+ "executables": [],+ "http_paths": [+ "/api/multi-user/admin/books"+ ]+}diff --git a/deeptutor/modules/manifests/calendar.json b/deeptutor/modules/manifests/calendar.jsonnew file mode 100644index 000000000..1a88601a9--- /dev/null+++ b/deeptutor/modules/manifests/calendar.json@@ -0,0 +1,53 @@+{+ "schema_version": 1,+ "id": "calendar",+ "distribution": "deeptutor-calendar",+ "requires": [],+ "optional": [+ "mastery",+ "partners"+ ],+ "paths": [+ "deeptutor/services/calendar",+ "deeptutor/services/cron",+ "deeptutor/api/routers/calendar.py",+ "deeptutor/tools/cron_tool.py"+ ],+ "capabilities": {},+ "loops": {},+ "tools": {+ "cron": {+ "class_path": "deeptutor.tools.builtin:CronTool",+ "order": 24+ }+ },+ "routes": [+ {+ "reference": "deeptutor.api.routers.calendar:router",+ "options": {+ "prefix": "/api/calendar",+ "tags": [+ "calendar"+ ]+ },+ "auth": "learning",+ "order": 640+ }+ ],+ "commands": [],+ "navigation": [+ "/calendar"+ ],+ "services": [+ {+ "id": "cron",+ "start": "deeptutor.services.cron.module_service:start_cron",+ "stop": "deeptutor.services.cron.module_service:stop_cron"+ }+ ],+ "requirements": [+ "croniter>=6.0.0,<7.0.0",+ "python-dateutil>=2.9.0,<3.0.0"+ ],+ "executables": []+}diff --git a/deeptutor/modules/manifests/co-writer.json b/deeptutor/modules/manifests/co-writer.jsonnew file mode 100644index 000000000..6cb520343--- /dev/null+++ b/deeptutor/modules/manifests/co-writer.json@@ -0,0 +1,59 @@+{+ "schema_version": 1,+ "id": "co-writer",+ "distribution": "deeptutor-co-writer",+ "requires": [+ "knowledge"+ ],+ "optional": [],+ "paths": [+ "deeptutor/co_writer",+ "deeptutor/api/routers/co_writer.py",+ "deeptutor/capabilities/notes",+ "deeptutor/notes"+ ],+ "capabilities": {},+ "loops": {+ "notes": {+ "class_path": "deeptutor.capabilities.notes.capability:NotesCapability"+ }+ },+ "tools": {+ "write_note": {+ "class_path": "deeptutor.capabilities.notes.tools:WriteNoteTool",+ "order": 0+ },+ "search_notes": {+ "class_path": "deeptutor.capabilities.notes.tools:SearchNotesTool",+ "order": 1+ },+ "note_read": {+ "class_path": "deeptutor.capabilities.notes.tools:NoteReadTool",+ "order": 2+ },+ "note_suggest": {+ "class_path": "deeptutor.capabilities.notes.tools:NoteSuggestTool",+ "order": 3+ }+ },+ "routes": [+ {+ "reference": "deeptutor.api.routers.co_writer:router",+ "options": {+ "prefix": "/api",+ "tags": [+ "documents"+ ]+ },+ "auth": "learning",+ "order": 628+ }+ ],+ "commands": [],+ "navigation": [+ "/co-writer"+ ],+ "services": [],+ "requirements": [],+ "executables": []+}diff --git a/deeptutor/modules/manifests/core.json b/deeptutor/modules/manifests/core.jsonnew file mode 100644index 000000000..14e01942c--- /dev/null+++ b/deeptutor/modules/manifests/core.json@@ -0,0 +1,210 @@+{+ "schema_version": 1,+ "id": "core",+ "distribution": "deeptutor",+ "requires": [],+ "optional": [],+ "paths": [+ "deeptutor/knowledge/manifest.py",+ "deeptutor/knowledge/kb_types.py"+ ],+ "capabilities": {+ "chat": {+ "class_path": "deeptutor.agents.chat.capability:ChatCapability",+ "config_model": "deeptutor.runtime.request_contracts:ChatRequestConfig",+ "manifest": {+ "name": "chat",+ "description": "Agentic chat: an exploring agent loop with tools, followed by a respond stage that streams the answer.",+ "stages": [+ "exploring",+ "responding"+ ],+ "tools_used": [+ "brainstorm",+ "web_search",+ "paper_search",+ "zotero_search",+ "reason",+ "geogebra_analysis",+ "imagegen",+ "videogen"+ ],+ "cli_aliases": [+ "chat"+ ]+ },+ "order": 0+ },+ "ask_questions": {+ "class_path": "deeptutor.capabilities.ask_questions.capability:AskQuestionsCapability",+ "config_model": "deeptutor.runtime.request_contracts:AskQuestionsRequestConfig",+ "manifest": {+ "name": "ask_questions",+ "description": "Ask the user high-value questions to fill in missing context, then complete the original request with their answers.",+ "stages": [+ "responding"+ ],+ "tools_used": [+ "ask_user"+ ],+ "cli_aliases": [+ "ask"+ ]+ },+ "order": 1+ }+ },+ "loops": {+ "ask_questions": {+ "class_path": "deeptutor.capabilities.ask_questions.loop:AskQuestionsLoopCapability"+ },+ "subagent": {+ "class_path": "deeptutor.capabilities.subagent.capability:SubagentCapability"+ },+ "explore_context": {+ "class_path": "deeptutor.capabilities.explore_context.capability:ExploreContextCapability"+ },+ "setup": {+ "class_path": "deeptutor.capabilities.setup.capability:SetupCapability"+ }+ },+ "tools": {+ "brainstorm": {+ "class_path": "deeptutor.tools.builtin:BrainstormTool",+ "order": 4+ },+ "web_search": {+ "class_path": "deeptutor.tools.builtin:WebSearchTool",+ "order": 8+ },+ "reason": {+ "class_path": "deeptutor.tools.builtin:ReasonTool",+ "order": 9+ },+ "zotero_search": {+ "class_path": "deeptutor.tools.builtin:ZoteroSearchToolWrapper",+ "order": 11+ },+ "read_source": {+ "class_path": "deeptutor.tools.builtin:ReadSourceTool",+ "order": 12+ },+ "read_skill": {+ "class_path": "deeptutor.tools.builtin:ReadSkillTool",+ "order": 15+ },+ "load_tools": {+ "class_path": "deeptutor.tools.builtin:LoadToolsTool",+ "order": 16+ },+ "web_fetch": {+ "class_path": "deeptutor.tools.builtin:WebFetchTool",+ "order": 17+ },+ "github": {+ "class_path": "deeptutor.tools.builtin:GithubTool",+ "order": 22+ },+ "ask_user": {+ "class_path": "deeptutor.tools.builtin:AskUserTool",+ "order": 23+ },+ "geogebra_analysis": {+ "class_path": "deeptutor.tools.builtin:GeoGebraAnalysisTool",+ "order": 25+ },+ "learning_status": {+ "class_path": "deeptutor.tools.learning_journal_tools:LearningStatusTool",+ "order": 26+ },+ "learning_update": {+ "class_path": "deeptutor.tools.learning_journal_tools:LearningUpdateTool",+ "order": 27+ },+ "exec": {+ "class_path": "deeptutor.tools.exec_tool:ExecTool",+ "order": 31+ },+ "workspace_list": {+ "class_path": "deeptutor.tools.workspace:WorkspaceListTool",+ "order": 32+ },+ "workspace_read": {+ "class_path": "deeptutor.tools.workspace:WorkspaceReadTool",+ "order": 33+ },+ "workspace_search": {+ "class_path": "deeptutor.tools.workspace:WorkspaceSearchTool",+ "order": 34+ },+ "workspace_present": {+ "class_path": "deeptutor.tools.workspace:WorkspacePresentTool",+ "order": 35+ },+ "workspace_export": {+ "class_path": "deeptutor.tools.workspace:WorkspaceExportTool",+ "order": 36+ },+ "imagegen": {+ "class_path": "deeptutor.tools.media_gen_tool:ImagegenTool",+ "order": 38+ },+ "videogen": {+ "class_path": "deeptutor.tools.media_gen_tool:VideogenTool",+ "order": 39+ },+ "consult_subagent": {+ "class_path": "deeptutor.capabilities.subagent.tools:ConsultSubagentTool",+ "order": 79+ },+ "inspect_setup": {+ "class_path": "deeptutor.capabilities.setup.tools:InspectSetupTool",+ "order": 93+ },+ "apply_setting": {+ "class_path": "deeptutor.capabilities.setup.tools:ApplySettingTool",+ "order": 94+ },+ "request_credential": {+ "class_path": "deeptutor.capabilities.setup.tools:RequestCredentialTool",+ "order": 95+ },+ "run_setup_job": {+ "class_path": "deeptutor.capabilities.setup.tools:RunSetupJobTool",+ "order": 96+ }+ },+ "routes": [],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [+ "PyYAML>=6.0",+ "jinja2>=3.1.0",+ "openai>=1.30.0",+ "tiktoken>=0.5.0",+ "aiohttp>=3.9.4",+ "httpx>=0.27.0",+ "requests>=2.32.2",+ "ddgs>=9.9.1",+ "nest_asyncio>=1.5.8",+ "tenacity>=8.0.0",+ "pydantic>=2.0.0",+ "pydantic-settings>=2.0.0",+ "packaging>=24.2",+ "jsonschema>=4.20.0,<5.0.0",+ "aiosqlite>=0.19.0",+ "typer>=0.9.0",+ "rich>=13.0.0",+ "prompt_toolkit>=3.0.36",+ "pyte>=0.8.1",+ "mcp>=1.26.0,<2.0.0",+ "tzdata>=2024.1",+ "loguru>=0.7.3,<1.0.0",+ "json-repair>=0.57.0,<1.0.0",+ "psutil>=5.9.0,<8.0.0",+ "python-docx>=1.1.0",+ "openpyxl>=3.1.0"+ ],+ "executables": []+}diff --git a/deeptutor/modules/manifests/knowledge.json b/deeptutor/modules/manifests/knowledge.jsonnew file mode 100644index 000000000..56b07ae2d--- /dev/null+++ b/deeptutor/modules/manifests/knowledge.json@@ -0,0 +1,205 @@+{+ "schema_version": 1,+ "id": "knowledge",+ "distribution": "deeptutor-knowledge",+ "requires": [+ "parsing"+ ],+ "optional": [+ "memory"+ ],+ "paths": [+ "deeptutor/services/rag",+ "deeptutor/services/embedding",+ "deeptutor/capabilities/obsidian",+ "deeptutor/capabilities/marginnote4",+ "deeptutor/capabilities/ima",+ "deeptutor_cli/kb.py",+ "deeptutor/api/routers/knowledge.py",+ "deeptutor/api/routers/marginnote4.py",+ "deeptutor/knowledge",+ "deeptutor/services/github_source",+ "deeptutor/services/web_source",+ "deeptutor/services/config/knowledge_base_config.py",+ "deeptutor/services/workspace/kb_move.py",+ "deeptutor/tools/rag_tool.py"+ ],+ "capabilities": {},+ "loops": {+ "obsidian": {+ "class_path": "deeptutor.capabilities.obsidian.capability:ObsidianCapability"+ },+ "marginnote4": {+ "class_path": "deeptutor.capabilities.marginnote4.capability:MarginNoteCapability"+ },+ "ima": {+ "class_path": "deeptutor.capabilities.ima.capability:ImaCapability"+ }+ },+ "tools": {+ "rag": {+ "class_path": "deeptutor.tools.builtin:RAGTool",+ "order": 5+ },+ "kb_files": {+ "class_path": "deeptutor.tools.builtin:KbFilesTool",+ "order": 6+ },+ "obsidian_search": {+ "class_path": "deeptutor.capabilities.obsidian.tools:ObsidianSearchTool",+ "order": 63+ },+ "obsidian_read": {+ "class_path": "deeptutor.capabilities.obsidian.tools:ObsidianReadTool",+ "order": 64+ },+ "obsidian_list": {+ "class_path": "deeptutor.capabilities.obsidian.tools:ObsidianListTool",+ "order": 65+ },+ "obsidian_backlinks": {+ "class_path": "deeptutor.capabilities.obsidian.tools:ObsidianBacklinksTool",+ "order": 66+ },+ "obsidian_links": {+ "class_path": "deeptutor.capabilities.obsidian.tools:ObsidianLinksTool",+ "order": 67+ },+ "obsidian_tags": {+ "class_path": "deeptutor.capabilities.obsidian.tools:ObsidianTagsTool",+ "order": 68+ },+ "obsidian_create_note": {+ "class_path": "deeptutor.capabilities.obsidian.tools:ObsidianCreateNoteTool",+ "order": 69+ },+ "obsidian_append": {+ "class_path": "deeptutor.capabilities.obsidian.tools:ObsidianAppendTool",+ "order": 70+ },+ "obsidian_set_property": {+ "class_path": "deeptutor.capabilities.obsidian.tools:ObsidianSetPropertyTool",+ "order": 71+ },+ "marginnote_search": {+ "class_path": "deeptutor.capabilities.marginnote4.tools:MarginNoteSearchTool",+ "order": 72+ },+ "marginnote_read": {+ "class_path": "deeptutor.capabilities.marginnote4.tools:MarginNoteReadTool",+ "order": 73+ },+ "marginnote_list": {+ "class_path": "deeptutor.capabilities.marginnote4.tools:MarginNoteListTool",+ "order": 74+ },+ "marginnote_documents": {+ "class_path": "deeptutor.capabilities.marginnote4.tools:MarginNoteDocumentsTool",+ "order": 75+ },+ "marginnote_links": {+ "class_path": "deeptutor.capabilities.marginnote4.tools:MarginNoteLinksTool",+ "order": 76+ },+ "marginnote_tags": {+ "class_path": "deeptutor.capabilities.marginnote4.tools:MarginNoteTagsTool",+ "order": 77+ },+ "marginnote_cards": {+ "class_path": "deeptutor.capabilities.marginnote4.tools:MarginNoteCardsTool",+ "order": 78+ },+ "ima_list": {+ "class_path": "deeptutor.capabilities.ima.tools:ImaListTool",+ "order": 80+ },+ "ima_read": {+ "class_path": "deeptutor.capabilities.ima.tools:ImaReadTool",+ "order": 81+ },+ "ima_note_search": {+ "class_path": "deeptutor.capabilities.ima.tools:ImaNoteSearchTool",+ "order": 82+ },+ "ima_add_url": {+ "class_path": "deeptutor.capabilities.ima.tools:ImaAddUrlTool",+ "order": 83+ },+ "ima_write_note": {+ "class_path": "deeptutor.capabilities.ima.tools:ImaWriteNoteTool",+ "order": 84+ }+ },+ "routes": [+ {+ "reference": "deeptutor.api.routers.knowledge:router",+ "options": {+ "prefix": "/api",+ "tags": [+ "knowledge-bases"+ ]+ },+ "auth": "learning",+ "order": 578+ },+ {+ "reference": "deeptutor.api.routers.knowledge:ws_router",+ "options": {+ "prefix": "/ws",+ "tags": [+ "knowledge-bases"+ ]+ },+ "auth": "public",+ "order": 620+ },+ {+ "reference": "deeptutor.api.routers.marginnote4:router",+ "options": {+ "prefix": "/api/marginnote4",+ "tags": [+ "marginnote4"+ ]+ },+ "auth": "public",+ "order": 830+ }+ ],+ "commands": [+ {+ "name": "kb",+ "register": "deeptutor_cli.kb:register",+ "help": "Manage kb."+ }+ ],+ "navigation": [+ "/knowledge-bases"+ ],+ "services": [+ {+ "id": "github_sync",+ "start": "deeptutor.knowledge.module_service:start_github_sync",+ "stop": "deeptutor.knowledge.module_service:stop_github_sync"+ },+ {+ "id": "web_source_sync",+ "start": "deeptutor.knowledge.module_service:start_web_source_sync",+ "stop": "deeptutor.knowledge.module_service:stop_web_source_sync"+ }+ ],+ "requirements": [+ "pageindex>=0.2.10,<0.3.0",+ "llama-index>=0.14.12",+ "bm25s>=0.3.14,<0.4.0",+ "llama-index-retrievers-bm25>=0.7.1,<0.8.0; python_version < '3.14'",+ "llama-index-vector-stores-faiss>=0.4.0,<1.0.0",+ "faiss-cpu>=1.8.0,<2.0.0; python_version < '3.14'",+ "faiss-cpu>=1.12.0,<2.0.0; python_version >= '3.14'",+ "numpy>=1.24.0,<3.0.0"+ ],+ "executables": [],+ "http_paths": [+ "/api/subagents/connections",+ "/api/settings/workspace/knowledge-bases"+ ]+}diff --git a/deeptutor/modules/manifests/mastery.json b/deeptutor/modules/manifests/mastery.jsonnew file mode 100644index 000000000..11921168c--- /dev/null+++ b/deeptutor/modules/manifests/mastery.json@@ -0,0 +1,179 @@+{+ "schema_version": 1,+ "id": "mastery",+ "distribution": "deeptutor-mastery",+ "requires": [+ "knowledge"+ ],+ "optional": [+ "books",+ "notebook",+ "co-writer",+ "reading"+ ],+ "paths": [+ "deeptutor/capabilities/mastery",+ "deeptutor/learning",+ "deeptutor/api/routers/mastery_path.py",+ "deeptutor/tools/mastery_nav.py",+ "deeptutor/tools/mastery_tool.py",+ "deeptutor/services/mastery_hints.py"+ ],+ "capabilities": {+ "mastery_path": {+ "class_path": "deeptutor.capabilities.mastery.capability:MasteryPathCapability",+ "config_model": "deeptutor.runtime.request_contracts:MasteryPathRequestConfig",+ "manifest": {+ "name": "mastery_path",+ "description": "Mastery-based tutoring: a dedicated agent loop drives an adaptive mastery path with a hard, per-type mastery gate and spaced review.",+ "stages": [+ "responding"+ ],+ "tools_used": [+ "mastery_prepare_lesson",+ "mastery_status",+ "mastery_quiz",+ "mastery_note_explained",+ "mastery_grade",+ "mastery_skip_question",+ "mastery_repair_question",+ "mastery_defer_objective",+ "mastery_assess",+ "mastery_build",+ "mastery_mode",+ "mastery_profile",+ "mastery_revise",+ "mastery_paths",+ "mastery_switch",+ "mastery_leave",+ "rag",+ "read_source",+ "ask_user"+ ],+ "cli_aliases": [+ "mastery"+ ]+ },+ "order": 8+ }+ },+ "loops": {+ "mastery": {+ "class_path": "deeptutor.capabilities.mastery.loop:MasteryLoopCapability"+ }+ },+ "tools": {+ "mastery_topics": {+ "class_path": "deeptutor.tools.mastery_nav:MasteryTopicsTool",+ "order": 40+ },+ "mastery_sessions": {+ "class_path": "deeptutor.tools.mastery_nav:MasterySessionsTool",+ "order": 41+ },+ "mastery_open_session": {+ "class_path": "deeptutor.tools.mastery_nav:MasteryOpenSessionTool",+ "order": 42+ },+ "mastery_new_session": {+ "class_path": "deeptutor.tools.mastery_nav:MasteryNewSessionTool",+ "order": 43+ },+ "mastery_status": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryStatusTool",+ "order": 44+ },+ "mastery_prepare_lesson": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryPrepareLessonTool",+ "order": 45+ },+ "mastery_quiz": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryQuizTool",+ "order": 46+ },+ "mastery_note_explained": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryNoteExplainedTool",+ "order": 47+ },+ "mastery_grade": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryGradeTool",+ "order": 48+ },+ "mastery_skip_question": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasterySkipQuestionTool",+ "order": 49+ },+ "mastery_repair_question": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryRepairQuestionTool",+ "order": 50+ },+ "mastery_defer_objective": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryDeferObjectiveTool",+ "order": 51+ },+ "mastery_assess": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryAssessTool",+ "order": 52+ },+ "mastery_build": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryBuildTool",+ "order": 53+ },+ "mastery_mode": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryModeTool",+ "order": 54+ },+ "mastery_profile": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryProfileTool",+ "order": 55+ },+ "mastery_revise": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryReviseTool",+ "order": 56+ },+ "mastery_paths": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryPathsTool",+ "order": 57+ },+ "mastery_switch": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasterySwitchTool",+ "order": 58+ },+ "mastery_leave": {+ "class_path": "deeptutor.capabilities.mastery.tools:MasteryLeaveTool",+ "order": 59+ }+ },+ "routes": [+ {+ "reference": "deeptutor.api.routers.mastery_path:router",+ "options": {+ "prefix": "/api/mastery-paths",+ "tags": [+ "mastery-path"+ ]+ },+ "auth": "learning",+ "order": 602+ },+ {+ "reference": "deeptutor.api.routers.mastery_path:ws_router",+ "options": {+ "prefix": "/ws",+ "tags": [+ "mastery-path"+ ]+ },+ "auth": "public",+ "order": 623+ }+ ],+ "commands": [],+ "navigation": [+ "/mastery",+ "/learning/mastery"+ ],+ "services": [],+ "requirements": [],+ "executables": []+}diff --git a/deeptutor/modules/manifests/memory.json b/deeptutor/modules/manifests/memory.jsonnew file mode 100644index 000000000..b04a99a8d--- /dev/null+++ b/deeptutor/modules/manifests/memory.json@@ -0,0 +1,51 @@+{+ "schema_version": 1,+ "id": "memory",+ "distribution": "deeptutor-memory",+ "requires": [],+ "optional": [],+ "paths": [+ "deeptutor/services/memory",+ "deeptutor_cli/memory.py",+ "deeptutor/api/routers/memory.py",+ "deeptutor/agents/loop/native_memory.py"+ ],+ "capabilities": {},+ "loops": {},+ "tools": {+ "read_memory": {+ "class_path": "deeptutor.tools.builtin:ReadMemoryTool",+ "order": 13+ },+ "write_memory": {+ "class_path": "deeptutor.tools.builtin:WriteMemoryTool",+ "order": 14+ }+ },+ "routes": [+ {+ "reference": "deeptutor.api.routers.memory:router",+ "options": {+ "prefix": "/api/memory",+ "tags": [+ "memory"+ ]+ },+ "auth": "learning",+ "order": 662+ }+ ],+ "commands": [+ {+ "name": "memory",+ "register": "deeptutor_cli.memory:register",+ "help": "Manage memory."+ }+ ],+ "navigation": [+ "/memory"+ ],+ "services": [],+ "requirements": [],+ "executables": []+}diff --git a/deeptutor/modules/manifests/notebook.json b/deeptutor/modules/manifests/notebook.jsonnew file mode 100644index 000000000..40a2073a9--- /dev/null+++ b/deeptutor/modules/manifests/notebook.json@@ -0,0 +1,55 @@+{+ "schema_version": 1,+ "id": "notebook",+ "distribution": "deeptutor-notebook",+ "requires": [],+ "optional": [],+ "paths": [+ "deeptutor/services/notebook",+ "deeptutor_cli/notebook.py",+ "deeptutor/api/routers/notebook.py"+ ],+ "capabilities": {},+ "loops": {},+ "tools": {+ "list_notebook": {+ "class_path": "deeptutor.tools.builtin:ListNotebookTool",+ "order": 18+ },+ "list_favorites": {+ "class_path": "deeptutor.tools.builtin:ListFavoritesTool",+ "order": 19+ },+ "save_favorite": {+ "class_path": "deeptutor.tools.builtin:SaveFavoriteTool",+ "order": 20+ }+ },+ "routes": [+ {+ "reference": "deeptutor.api.routers.notebook:router",+ "options": {+ "prefix": "/api",+ "tags": [+ "notebooks"+ ]+ },+ "auth": "learning",+ "order": 631+ }+ ],+ "commands": [+ {+ "name": "notebook",+ "register": "deeptutor_cli.notebook:register",+ "help": "Manage notebook."+ }+ ],+ "navigation": [+ "/notebooks",+ "/learning/practice"+ ],+ "services": [],+ "requirements": [],+ "executables": []+}diff --git a/deeptutor/modules/manifests/parser-docling.json b/deeptutor/modules/manifests/parser-docling.jsonnew file mode 100644index 000000000..a4fa38276--- /dev/null+++ b/deeptutor/modules/manifests/parser-docling.json@@ -0,0 +1,23 @@+{+ "schema_version": 1,+ "id": "parser-docling",+ "distribution": "deeptutor-parser-docling",+ "requires": [+ "parsing"+ ],+ "optional": [],+ "paths": [],+ "capabilities": {},+ "loops": {},+ "tools": {},+ "routes": [],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [+ "docling[xbrl]>=2.123.1",+ "docling-slim[format-iwork,format-opendocument,format-video]>=2.123.1"+ ],+ "executables": [],+ "parser_engine": "docling"+}diff --git a/deeptutor/modules/manifests/parser-liteparse.json b/deeptutor/modules/manifests/parser-liteparse.jsonnew file mode 100644index 000000000..229493555--- /dev/null+++ b/deeptutor/modules/manifests/parser-liteparse.json@@ -0,0 +1,22 @@+{+ "schema_version": 1,+ "id": "parser-liteparse",+ "distribution": "deeptutor-parser-liteparse",+ "requires": [+ "parsing"+ ],+ "optional": [],+ "paths": [],+ "capabilities": {},+ "loops": {},+ "tools": {},+ "routes": [],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [+ "liteparse>=2.14.2"+ ],+ "executables": [],+ "parser_engine": "liteparse"+}diff --git a/deeptutor/modules/manifests/parser-markitdown.json b/deeptutor/modules/manifests/parser-markitdown.jsonnew file mode 100644index 000000000..b68705d14--- /dev/null+++ b/deeptutor/modules/manifests/parser-markitdown.json@@ -0,0 +1,22 @@+{+ "schema_version": 1,+ "id": "parser-markitdown",+ "distribution": "deeptutor-parser-markitdown",+ "requires": [+ "parsing"+ ],+ "optional": [],+ "paths": [],+ "capabilities": {},+ "loops": {},+ "tools": {},+ "routes": [],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [+ "markitdown[all]>=0.1.7"+ ],+ "executables": [],+ "parser_engine": "markitdown"+}diff --git a/deeptutor/modules/manifests/parser-pymupdf4llm.json b/deeptutor/modules/manifests/parser-pymupdf4llm.jsonnew file mode 100644index 000000000..05b63b3d6--- /dev/null+++ b/deeptutor/modules/manifests/parser-pymupdf4llm.json@@ -0,0 +1,22 @@+{+ "schema_version": 1,+ "id": "parser-pymupdf4llm",+ "distribution": "deeptutor-parser-pymupdf4llm",+ "requires": [+ "parsing"+ ],+ "optional": [],+ "paths": [],+ "capabilities": {},+ "loops": {},+ "tools": {},+ "routes": [],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [+ "pymupdf4llm>=1.28.2"+ ],+ "executables": [],+ "parser_engine": "pymupdf4llm"+}diff --git a/deeptutor/modules/manifests/parsing.json b/deeptutor/modules/manifests/parsing.jsonnew file mode 100644index 000000000..18ae7c52f--- /dev/null+++ b/deeptutor/modules/manifests/parsing.json@@ -0,0 +1,35 @@+{+ "schema_version": 1,+ "id": "parsing",+ "distribution": "deeptutor-parsing",+ "requires": [],+ "optional": [],+ "paths": [+ "deeptutor/services/parsing",+ "deeptutor/textbook_struct"+ ],+ "capabilities": {},+ "loops": {},+ "tools": {},+ "routes": [],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [+ "PyMuPDF>=1.26.0",+ "Pillow>=10.0.0",+ "python-docx>=1.1.0",+ "openpyxl>=3.1.0",+ "python-pptx>=1.0.0",+ "pypdf>=4.0.0",+ "pdfplumber>=0.11.0",+ "reportlab>=4.0.0",+ "defusedxml>=0.7.1",+ "pywin32; sys_platform == 'win32'"+ ],+ "executables": [],+ "http_paths": [+ "/api/settings/document-parsing",+ "/api/settings/mineru"+ ]+}diff --git a/deeptutor/modules/manifests/partners.json b/deeptutor/modules/manifests/partners.jsonnew file mode 100644index 000000000..b5eb6d6d1--- /dev/null+++ b/deeptutor/modules/manifests/partners.json@@ -0,0 +1,139 @@+{+ "schema_version": 1,+ "id": "partners",+ "distribution": "deeptutor-partners",+ "requires": [+ "memory"+ ],+ "optional": [+ "calendar",+ "knowledge"+ ],+ "paths": [+ "deeptutor/partners",+ "deeptutor/services/partners",+ "deeptutor/services/partner_groups",+ "deeptutor/capabilities/partner_authoring",+ "deeptutor/capabilities/partner_group",+ "deeptutor/capabilities/handoff",+ "deeptutor_cli/partner.py",+ "deeptutor/api/routers/partner_groups.py",+ "deeptutor/api/routers/partners.py",+ "deeptutor/api/routers/_partners_channel_schema.py",+ "deeptutor/tools/partner_memory.py"+ ],+ "capabilities": {},+ "loops": {+ "partner_authoring": {+ "class_path": "deeptutor.capabilities.partner_authoring.capability:PartnerAuthoringCapability"+ },+ "partner_group": {+ "class_path": "deeptutor.capabilities.partner_group.capability:PartnerGroupCapability"+ }+ },+ "tools": {+ "propose_partner": {+ "class_path": "deeptutor.capabilities.partner_authoring.tools:ProposePartnerTool",+ "order": 97+ },+ "invoke_other": {+ "class_path": "deeptutor.capabilities.partner_group.tools:InvokeOtherTool",+ "order": 98+ },+ "partner_read": {+ "class_path": "deeptutor.tools.partner_memory:PartnerReadTool",+ "order": 99+ },+ "partner_memorize": {+ "class_path": "deeptutor.tools.partner_memory:PartnerMemorizeTool",+ "order": 100+ },+ "partner_search": {+ "class_path": "deeptutor.tools.partner_memory:PartnerSearchTool",+ "order": 101+ }+ },+ "routes": [+ {+ "reference": "deeptutor.api.routers.partners:router",+ "options": {+ "prefix": "/api/partners",+ "tags": [+ "partners"+ ]+ },+ "auth": "learning",+ "order": 801+ },+ {+ "reference": "deeptutor.api.routers.partner_groups:router",+ "options": {+ "prefix": "/api/partner-groups",+ "tags": [+ "partner-groups"+ ]+ },+ "auth": "learning",+ "order": 807+ },+ {+ "reference": "deeptutor.api.routers.partners:ws_router",+ "options": {+ "prefix": "/ws/partners",+ "tags": [+ "partners"+ ]+ },+ "auth": "public",+ "order": 813+ },+ {+ "reference": "deeptutor.api.routers.partner_groups:ws_router",+ "options": {+ "prefix": "/ws/partner-groups",+ "tags": [+ "partner-groups"+ ]+ },+ "auth": "public",+ "order": 816+ }+ ],+ "commands": [+ {+ "name": "partner",+ "register": "deeptutor_cli.partner:register",+ "help": "Manage partner."+ }+ ],+ "navigation": [+ "/partners"+ ],+ "services": [+ {+ "id": "partners",+ "start": "deeptutor.services.partners.module_service:start_partners",+ "stop": "deeptutor.services.partners.module_service:stop_partners"+ }+ ],+ "requirements": [+ "qrcode>=7.4.0,<9.0.0",+ "python-telegram-bot[socks]>=22.6,<23.0",+ "wecom-aibot-sdk>=1.0.8,<2.0.0",+ "lark-oapi>=1.5.0,<2.0.0",+ "dingtalk-stream>=0.24.0,<1.0.0",+ "slack-sdk>=3.39.0,<4.0.0",+ "slackify-markdown>=0.2.0,<1.0.0",+ "qq-botpy>=1.2.0,<2.0.0",+ "python-socketio>=5.16.0,<6.0.0",+ "msgpack>=1.1.0,<2.0.0",+ "python-socks[asyncio]>=2.8.0,<3.0.0",+ "socksio>=1.0.0,<2.0.0",+ "websocket-client>=1.9.0,<2.0.0",+ "zulip>=0.8.0,<1.0.0",+ "websockets>=12.0",+ "aiohttp>=3.10.0,<4.0.0",+ "PyJWT[crypto]>=2.8.0,<3.0.0"+ ],+ "executables": []+}diff --git a/deeptutor/modules/manifests/providers.json b/deeptutor/modules/manifests/providers.jsonnew file mode 100644index 000000000..2d61f40e5--- /dev/null+++ b/deeptutor/modules/manifests/providers.json@@ -0,0 +1,22 @@+{+ "schema_version": 1,+ "id": "providers",+ "distribution": "deeptutor-providers",+ "requires": [],+ "optional": [],+ "paths": [],+ "capabilities": {},+ "loops": {},+ "tools": {},+ "routes": [],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [+ "anthropic>=0.30.0",+ "dashscope>=1.14.0",+ "perplexityai>=0.1.0",+ "oauth-cli-kit>=0.1.1"+ ],+ "executables": []+}diff --git a/deeptutor/modules/manifests/questions.json b/deeptutor/modules/manifests/questions.jsonnew file mode 100644index 000000000..14fd52189--- /dev/null+++ b/deeptutor/modules/manifests/questions.json@@ -0,0 +1,99 @@+{+ "schema_version": 1,+ "id": "questions",+ "distribution": "deeptutor-questions",+ "requires": [+ "parsing"+ ],+ "optional": [+ "knowledge"+ ],+ "paths": [+ "deeptutor/agents/question",+ "deeptutor/api/routers/practice.py",+ "deeptutor/api/routers/question.py",+ "deeptutor/api/routers/question_notebook.py",+ "deeptutor/tools/question"+ ],+ "capabilities": {+ "deep_question": {+ "class_path": "deeptutor.agents.question.capability:DeepQuestionCapability",+ "config_model": "deeptutor.runtime.request_contracts:DeepQuestionRequestConfig",+ "manifest": {+ "name": "deep_question",+ "description": "Fast question generation (Template batches -> Generate).",+ "stages": [+ "ideation",+ "generation"+ ],+ "tools_used": [+ "rag",+ "web_search",+ "exec"+ ],+ "cli_aliases": [+ "quiz"+ ]+ },+ "order": 3+ }+ },+ "loops": {},+ "tools": {+ "question_bank": {+ "class_path": "deeptutor.tools.builtin:QuestionBankTool",+ "order": 21+ }+ },+ "routes": [+ {+ "reference": "deeptutor.api.routers.question:router",+ "options": {+ "prefix": "/api/question",+ "tags": [+ "question"+ ]+ },+ "auth": "learning",+ "order": 572+ },+ {+ "reference": "deeptutor.api.routers.question:ws_router",+ "options": {+ "prefix": "/ws/questions",+ "tags": [+ "question"+ ]+ },+ "auth": "public",+ "order": 617+ },+ {+ "reference": "deeptutor.api.routers.question_notebook:router",+ "options": {+ "prefix": "/api/question-notebook",+ "tags": [+ "question-notebook"+ ]+ },+ "auth": "learning",+ "order": 689+ },+ {+ "reference": "deeptutor.api.routers.practice:router",+ "options": {+ "prefix": "/api/question-notebook/practice",+ "tags": [+ "practice"+ ]+ },+ "auth": "learning",+ "order": 695+ }+ ],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [],+ "executables": []+}diff --git a/deeptutor/modules/manifests/reading.json b/deeptutor/modules/manifests/reading.jsonnew file mode 100644index 000000000..a24c71445--- /dev/null+++ b/deeptutor/modules/manifests/reading.json@@ -0,0 +1,169 @@+{+ "schema_version": 1,+ "id": "reading",+ "distribution": "deeptutor-reading",+ "requires": [+ "knowledge",+ "parsing",+ "mastery",+ "notebook"+ ],+ "optional": [],+ "paths": [+ "deeptutor/capabilities/reading",+ "deeptutor/reading",+ "deeptutor/video_learning",+ "deeptutor/api/routers/reading.py",+ "deeptutor/api/routers/reading_extensions.py",+ "deeptutor/api/routers/video_learning.py",+ "deeptutor/api/routers/voice.py",+ "deeptutor/services/reading_hints.py"+ ],+ "capabilities": {+ "immersive_reading": {+ "class_path": "deeptutor.capabilities.reading.mode:ImmersiveReadingCapability",+ "config_model": "deeptutor.runtime.request_contracts:ImmersiveReadingRequestConfig",+ "manifest": {+ "name": "immersive_reading",+ "description": "Read a document alongside the assistant, which cites the exact page or section behind every claim.",+ "stages": [+ "responding"+ ],+ "tools_used": [+ "reading_list_tabs",+ "reading_switch_tab",+ "material_outline",+ "search_material",+ "read_material",+ "view_figure",+ "reader_goto",+ "reader_annotate",+ "web_search",+ "exec",+ "reason"+ ],+ "cli_aliases": [+ "reading",+ "read"+ ]+ },+ "order": 9+ }+ },+ "loops": {+ "immersive_reading": {+ "class_path": "deeptutor.capabilities.reading.capability:ReadingCapability"+ }+ },+ "tools": {+ "reading_list_tabs": {+ "class_path": "deeptutor.capabilities.reading.tools:ReadingListTabsTool",+ "order": 85+ },+ "reading_switch_tab": {+ "class_path": "deeptutor.capabilities.reading.tools:ReadingSwitchTabTool",+ "order": 86+ },+ "material_outline": {+ "class_path": "deeptutor.capabilities.reading.tools:MaterialOutlineTool",+ "order": 87+ },+ "search_material": {+ "class_path": "deeptutor.capabilities.reading.tools:SearchMaterialTool",+ "order": 88+ },+ "read_material": {+ "class_path": "deeptutor.capabilities.reading.tools:ReadMaterialTool",+ "order": 89+ },+ "view_figure": {+ "class_path": "deeptutor.capabilities.reading.tools:ViewFigureTool",+ "order": 90+ },+ "reader_goto": {+ "class_path": "deeptutor.capabilities.reading.tools:ReaderGotoTool",+ "order": 91+ },+ "reader_annotate": {+ "class_path": "deeptutor.capabilities.reading.tools:ReaderAnnotateTool",+ "order": 92+ }+ },+ "routes": [+ {+ "reference": "deeptutor.api.routers.reading:router",+ "options": {+ "prefix": "/api/reading",+ "tags": [+ "reading"+ ]+ },+ "auth": "learning",+ "order": 650+ },+ {+ "reference": "deeptutor.api.routers.reading_extensions:router",+ "options": {+ "prefix": "/api/reading",+ "tags": [+ "reading-extensions"+ ]+ },+ "auth": "learning",+ "order": 656+ },+ {+ "reference": "deeptutor.api.routers.video_learning:settings_router",+ "options": {+ "prefix": "/api/settings/video-learning",+ "tags": [+ "video-learning-settings"+ ]+ },+ "auth": "admin",+ "order": 722+ },+ {+ "reference": "deeptutor.api.routers.voice:router",+ "options": {+ "prefix": "/api/voice",+ "tags": [+ "voice"+ ]+ },+ "auth": "learning",+ "order": 775+ },+ {+ "reference": "deeptutor.api.routers.video_learning:router",+ "options": {+ "prefix": "/api/video-learning",+ "tags": [+ "video-learning"+ ]+ },+ "auth": "learning",+ "order": 778+ }+ ],+ "commands": [],+ "navigation": [+ "/reading",+ "/learning/reading",+ "/learning/watching"+ ],+ "services": [],+ "requirements": [+ "youtube-transcript-api>=1.2.0,<2.0.0"+ ],+ "executables": [],+ "entry_points": {+ "deeptutor.reading_extensions": {+ "read_aloud": "deeptutor.reading.read_aloud:ReadAloudExtension",+ "guided_learning": "deeptutor.reading.study_guidance:StudyGuidanceExtension",+ "vocabulary": "deeptutor.reading.vocabulary:VocabularyExtension",+ "quiz": "deeptutor.reading.quiz:ReadingQuizExtension",+ "translation": "deeptutor.reading.translation:TranslationExtension"+ }+ }+}diff --git a/deeptutor/modules/manifests/renderer-manim.json b/deeptutor/modules/manifests/renderer-manim.jsonnew file mode 100644index 000000000..fbdba97f0--- /dev/null+++ b/deeptutor/modules/manifests/renderer-manim.json@@ -0,0 +1,52 @@+{+ "schema_version": 1,+ "id": "renderer-manim",+ "distribution": "deeptutor-renderer-manim",+ "requires": [],+ "optional": [],+ "paths": [+ "deeptutor/agents/math_animator"+ ],+ "capabilities": {+ "math_animator": {+ "class_path": "deeptutor.agents.math_animator.capability:MathAnimatorCapability",+ "config_model": "deeptutor.agents.math_animator.request_config:MathAnimatorRequestConfig",+ "manifest": {+ "name": "math_animator",+ "description": "Generate math animations or storyboard images with Manim.",+ "stages": [+ "concept_analysis",+ "concept_design",+ "code_generation",+ "code_retry",+ "summary",+ "render_output"+ ],+ "tools_used": [],+ "cli_aliases": [+ "animate"+ ],+ "config_defaults": {+ "output_mode": "video",+ "quality": "medium",+ "style_hint": ""+ }+ },+ "validator": "deeptutor.agents.math_animator.request_config:validate_math_animator_request_config",+ "order": 5+ }+ },+ "loops": {},+ "tools": {},+ "routes": [],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [+ "manim>=0.19.0"+ ],+ "executables": [+ "ffmpeg",+ "latex"+ ]+}diff --git a/deeptutor/modules/manifests/research.json b/deeptutor/modules/manifests/research.jsonnew file mode 100644index 000000000..4a44c8242--- /dev/null+++ b/deeptutor/modules/manifests/research.json@@ -0,0 +1,80 @@+{+ "schema_version": 1,+ "id": "research",+ "distribution": "deeptutor-research",+ "requires": [],+ "optional": [+ "knowledge"+ ],+ "paths": [+ "deeptutor/agents/research",+ "deeptutor/services/research",+ "deeptutor/tools/research_tools.py",+ "deeptutor/tools/paper_search_tool.py",+ "deeptutor/tools/knowledge_frontier.py"+ ],+ "capabilities": {+ "deep_research": {+ "class_path": "deeptutor.agents.research.capability:DeepResearchCapability",+ "config_model": "deeptutor.agents.research.request_config:DeepResearchRequestConfig",+ "manifest": {+ "name": "deep_research",+ "description": "Agentic-loop deep research with iterative report generation.",+ "stages": [+ "rephrasing",+ "decomposing",+ "researching",+ "reporting"+ ],+ "tools_used": [+ "rag",+ "web_search",+ "paper_search",+ "preprint",+ "research_audit",+ "research_lit",+ "exec"+ ],+ "cli_aliases": [+ "research"+ ]+ },+ "validator": "deeptutor.agents.research.request_config:validate_research_request_config",+ "order": 4+ }+ },+ "loops": {},+ "tools": {+ "preprint": {+ "class_path": "deeptutor.tools.research_tools:PreprintTool",+ "order": 28+ },+ "research_audit": {+ "class_path": "deeptutor.tools.research_tools:ResearchAuditTool",+ "order": 29+ },+ "research_lit": {+ "class_path": "deeptutor.tools.research_tools:ResearchLiteratureTool",+ "order": 30+ },+ "paper_search": {+ "class_path": "deeptutor.tools.builtin:PaperSearchToolWrapper",+ "order": 10+ },+ "knowledge_frontier": {+ "class_path": "deeptutor.tools.builtin:KnowledgeFrontierTool",+ "order": 7,+ "requires": [+ "knowledge"+ ]+ }+ },+ "routes": [],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [+ "arxiv>=2.0.0"+ ],+ "executables": []+}diff --git a/deeptutor/modules/manifests/server.json b/deeptutor/modules/manifests/server.jsonnew file mode 100644index 000000000..6be4057eb--- /dev/null+++ b/deeptutor/modules/manifests/server.json@@ -0,0 +1,347 @@+{+ "schema_version": 1,+ "id": "server",+ "distribution": "deeptutor-server",+ "requires": [],+ "optional": [],+ "paths": [+ "deeptutor/api"+ ],+ "capabilities": {},+ "loops": {},+ "tools": {},+ "routes": [+ {+ "reference": "deeptutor.api.routers.auth:router",+ "options": {+ "prefix": "/api/auth",+ "tags": [+ "auth"+ ]+ },+ "auth": "public",+ "order": 542+ },+ {+ "reference": "deeptutor.api.routers.outputs:router",+ "options": {+ "prefix": "/files/outputs",+ "tags": [+ "outputs"+ ]+ },+ "auth": "public",+ "order": 543+ },+ {+ "reference": "deeptutor.api.routers.workspace:files_router",+ "options": {+ "prefix": "/files/workspace-items",+ "tags": [+ "workspace"+ ]+ },+ "auth": "public",+ "order": 546+ },+ {+ "reference": "deeptutor.api.routers.multi_user:router",+ "options": {+ "prefix": "/api/multi-user",+ "tags": [+ "multi-user"+ ]+ },+ "auth": "learning",+ "order": 566+ },+ {+ "reference": "deeptutor.api.routers.file_preview:router",+ "options": {+ "prefix": "/api/file-preview",+ "tags": [+ "file-preview"+ ]+ },+ "auth": "authenticated",+ "order": 584+ },+ {+ "reference": "deeptutor.api.routers.imports:router",+ "options": {+ "prefix": "/api/imports",+ "tags": [+ "imports"+ ]+ },+ "auth": "learning",+ "order": 590+ },+ {+ "reference": "deeptutor.api.routers.dashboard:router",+ "options": {+ "prefix": "/api/dashboard",+ "tags": [+ "dashboard"+ ]+ },+ "auth": "learning",+ "order": 596+ },+ {+ "reference": "deeptutor.api.routers.file_library:router",+ "options": {+ "prefix": "/files/library",+ "tags": [+ "library"+ ]+ },+ "auth": "learning",+ "order": 608+ },+ {+ "reference": "deeptutor.api.routers.task_board:router",+ "options": {+ "prefix": "/api/task-board",+ "tags": [+ "task-board"+ ]+ },+ "auth": "learning",+ "order": 634+ },+ {+ "reference": "deeptutor.api.routers.learning_journal:router",+ "options": {+ "prefix": "/api/learning-journal",+ "tags": [+ "learning-journal"+ ]+ },+ "auth": "learning",+ "order": 665+ },+ {+ "reference": "deeptutor.api.routers.capabilities_settings:router",+ "options": {+ "prefix": "/api/capabilities",+ "tags": [+ "capabilities"+ ]+ },+ "auth": "learning",+ "order": 671+ },+ {+ "reference": "deeptutor.api.routers.capabilities:router",+ "options": {+ "prefix": "/api/capabilities",+ "tags": [+ "capabilities"+ ]+ },+ "auth": "learning",+ "order": 677+ },+ {+ "reference": "deeptutor.api.routers.sessions:router",+ "options": {+ "prefix": "/api/sessions",+ "tags": [+ "sessions"+ ]+ },+ "auth": "learning",+ "order": 683+ },+ {+ "reference": "deeptutor.api.routers.settings:public_router",+ "options": {+ "prefix": "/api/settings",+ "tags": [+ "settings"+ ]+ },+ "auth": "public",+ "order": 705+ },+ {+ "reference": "deeptutor.api.routers.settings:router",+ "options": {+ "prefix": "/api/settings",+ "tags": [+ "settings"+ ]+ },+ "auth": "learning",+ "order": 710+ },+ {+ "reference": "deeptutor.api.routers.workspace:settings_router",+ "options": {+ "prefix": "/api/settings/workspace",+ "tags": [+ "workspace-settings"+ ]+ },+ "auth": "learning",+ "order": 716+ },+ {+ "reference": "deeptutor.api.routers.mcp_settings:router",+ "options": {+ "prefix": "/api/settings/mcp",+ "tags": [+ "mcp-settings"+ ]+ },+ "auth": "learning",+ "order": 728+ },+ {+ "reference": "deeptutor.api.routers.space_mcp:router",+ "options": {+ "prefix": "/api/space/mcp",+ "tags": [+ "space-mcp"+ ]+ },+ "auth": "learning",+ "order": 738+ },+ {+ "reference": "deeptutor.api.routers.space_cli_apps:router",+ "options": {+ "prefix": "/api/space/cli-apps",+ "tags": [+ "space-cli-apps"+ ]+ },+ "auth": "learning",+ "order": 748+ },+ {+ "reference": "deeptutor.api.routers.skills:router",+ "options": {+ "prefix": "/api/skills",+ "tags": [+ "skills"+ ]+ },+ "auth": "learning",+ "order": 754+ },+ {+ "reference": "deeptutor.api.routers.subagents:router",+ "options": {+ "prefix": "/api/subagents",+ "tags": [+ "subagents"+ ]+ },+ "auth": "learning",+ "order": 757+ },+ {+ "reference": "deeptutor.api.routers.personas:router",+ "options": {+ "prefix": "/api",+ "tags": [+ "personas"+ ]+ },+ "auth": "learning",+ "order": 763+ },+ {+ "reference": "deeptutor.api.routers.plugins:router",+ "options": {+ "prefix": "/api/plugins",+ "tags": [+ "plugins"+ ]+ },+ "auth": "public",+ "order": 766+ },+ {+ "reference": "deeptutor.api.routers.tools:router",+ "options": {+ "prefix": "/api/tools",+ "tags": [+ "tools"+ ]+ },+ "auth": "learning",+ "order": 769+ },+ {+ "reference": "deeptutor.api.routers.system:router",+ "options": {+ "prefix": "/api/system",+ "tags": [+ "system"+ ]+ },+ "auth": "learning",+ "order": 772+ },+ {+ "reference": "deeptutor.api.routers.agent_config:router",+ "options": {+ "prefix": "/api/agent-config",+ "tags": [+ "agent-config"+ ]+ },+ "auth": "learning",+ "order": 790+ },+ {+ "reference": "deeptutor.api.routers.attachments:router",+ "options": {+ "prefix": "/files/attachments",+ "tags": [+ "attachments"+ ]+ },+ "auth": "learning",+ "order": 821+ },+ {+ "reference": "deeptutor.api.routers.unified_ws:router",+ "options": {+ "tags": [+ "unified-ws"+ ]+ },+ "auth": "public",+ "order": 838+ },+ {+ "reference": "deeptutor.api.routers.quiz_judge:router",+ "options": {+ "prefix": "/ws",+ "tags": [+ "quiz-judge"+ ]+ },+ "auth": "public",+ "order": 842+ }+ ],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [+ "fastapi>=0.100.0",+ "uvicorn[standard]>=0.24.0",+ "websockets>=12.0",+ "python-multipart>=0.0.6",+ "bcrypt>=4.0.0",+ "python-jose[cryptography]>=3.3.0",+ "pocketbase>=0.12.0",+ "redis>=5.0.0,<7.0.0"+ ],+ "executables": []+}diff --git a/deeptutor/modules/manifests/solve.json b/deeptutor/modules/manifests/solve.jsonnew file mode 100644index 000000000..6f770c0e6--- /dev/null+++ b/deeptutor/modules/manifests/solve.json@@ -0,0 +1,62 @@+{+ "schema_version": 1,+ "id": "solve",+ "distribution": "deeptutor-solve",+ "requires": [],+ "optional": [],+ "paths": [+ "deeptutor/capabilities/solve",+ "deeptutor/tools/solve_tool.py"+ ],+ "capabilities": {+ "deep_solve": {+ "class_path": "deeptutor.capabilities.solve.capability:DeepSolveCapability",+ "config_model": "deeptutor.runtime.request_contracts:DeepSolveRequestConfig",+ "manifest": {+ "name": "deep_solve",+ "description": "Multi-step problem solving driven by the chat agent loop.",+ "stages": [+ "responding"+ ],+ "tools_used": [+ "solve_plan",+ "solve_finish_step",+ "solve_replan",+ "rag",+ "exec",+ "geogebra_analysis",+ "reason"+ ],+ "cli_aliases": [+ "solve"+ ]+ },+ "order": 2+ }+ },+ "loops": {+ "solve": {+ "class_path": "deeptutor.capabilities.solve.loop:SolveLoopCapability"+ }+ },+ "tools": {+ "solve_plan": {+ "class_path": "deeptutor.capabilities.solve.tools:SolvePlanTool",+ "order": 60+ },+ "solve_finish_step": {+ "class_path": "deeptutor.capabilities.solve.tools:SolveFinishStepTool",+ "order": 61+ },+ "solve_replan": {+ "class_path": "deeptutor.capabilities.solve.tools:SolveReplanTool",+ "order": 62+ }+ },+ "routes": [],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [],+ "executables": []+}diff --git a/deeptutor/modules/manifests/video-lesson.json b/deeptutor/modules/manifests/video-lesson.jsonnew file mode 100644index 000000000..51f20f717--- /dev/null+++ b/deeptutor/modules/manifests/video-lesson.json@@ -0,0 +1,41 @@+{+ "schema_version": 1,+ "id": "video-lesson",+ "distribution": "deeptutor-video-lesson",+ "requires": [],+ "optional": [],+ "paths": [+ "deeptutor/agents/video_lesson"+ ],+ "capabilities": {+ "video_lesson": {+ "class_path": "deeptutor.agents.video_lesson.capability:VideoLessonCapability",+ "config_model": "deeptutor.runtime.request_contracts:VideoLessonRequestConfig",+ "manifest": {+ "name": "video_lesson",+ "description": "Generate an animated video lesson (Remotion) that plays in the browser.",+ "stages": [+ "code_generation",+ "render_check",+ "render_output"+ ],+ "tools_used": [],+ "cli_aliases": [+ "lesson"+ ]+ },+ "order": 6+ }+ },+ "loops": {},+ "tools": {},+ "routes": [],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [],+ "executables": [+ "node",+ "npm"+ ]+}diff --git a/deeptutor/modules/manifests/visualize.json b/deeptutor/modules/manifests/visualize.jsonnew file mode 100644index 000000000..2e095860f--- /dev/null+++ b/deeptutor/modules/manifests/visualize.json@@ -0,0 +1,72 @@+{+ "schema_version": 1,+ "id": "visualize",+ "distribution": "deeptutor-visualize",+ "requires": [],+ "optional": [+ "renderer-manim"+ ],+ "paths": [+ "deeptutor/agents/visualize",+ "deeptutor/visualizers",+ "deeptutor/api/routers/visualizers.py"+ ],+ "capabilities": {+ "visualize": {+ "class_path": "deeptutor.agents.visualize.capability:VisualizeCapability",+ "config_model": "deeptutor.runtime.request_contracts:VisualizeRequestConfig",+ "manifest": {+ "name": "visualize",+ "description": "Generate a validated visualization with any installed visualizer type, or render a Manim animation/storyboard artifact.",+ "stages": [+ "analyzing",+ "generating",+ "reviewing",+ "concept_analysis",+ "concept_design",+ "code_generation",+ "code_retry",+ "summary",+ "render_output"+ ],+ "tools_used": [+ "submit_visualization"+ ],+ "cli_aliases": [+ "visualize",+ "viz"+ ]+ },+ "order": 7+ }+ },+ "loops": {+ "visualization_generation": {+ "class_path": "deeptutor.visualizers.loop_capability:VisualizationLoopCapability"+ }+ },+ "tools": {+ "submit_visualization": {+ "class_path": "deeptutor.visualizers.tool:SubmitVisualizationTool",+ "order": 37+ }+ },+ "routes": [+ {+ "reference": "deeptutor.api.routers.visualizers:router",+ "options": {+ "prefix": "/api/visualizers",+ "tags": [+ "visualizers"+ ]+ },+ "auth": "learning",+ "order": 784+ }+ ],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [],+ "executables": []+}diff --git a/deeptutor/modules/manifests/web.json b/deeptutor/modules/manifests/web.jsonnew file mode 100644index 000000000..ac8b7e1ef--- /dev/null+++ b/deeptutor/modules/manifests/web.json@@ -0,0 +1,21 @@+{+ "schema_version": 1,+ "id": "web",+ "distribution": "deeptutor-web",+ "requires": [+ "server"+ ],+ "optional": [],+ "paths": [+ "deeptutor_web"+ ],+ "capabilities": {},+ "loops": {},+ "tools": {},+ "routes": [],+ "commands": [],+ "navigation": [],+ "services": [],+ "requirements": [],+ "executables": []+}diff --git a/deeptutor/modules/services.py b/deeptutor/modules/services.pynew file mode 100644index 000000000..a28481209--- /dev/null+++ b/deeptutor/modules/services.py@@ -0,0 +1,26 @@+"""Lazy service callbacks assembled in dependency order."""++from functools import partial+from importlib import import_module++from .catalog import dependency_order, manifests, module_enabled+++def module_service_callbacks(action, container):+ if action not in {"start", "stop"}:+ raise ValueError(action)+ names = dependency_order(list(manifests()))+ # BackgroundLeaderSupervisor reverses the started prefix at shutdown;+ # keep start/stop callback positions paired, including partial startup.+ callbacks = []+ for name in names:+ if not module_enabled(name):+ continue+ for service in manifests()[name]["services"]:++ async def invoke(reference, owner):+ module, attribute = reference.split(":", 1)+ await getattr(import_module(module), attribute)(owner)++ callbacks.append(partial(invoke, service[action], container))+ return callbacksdiff --git a/deeptutor/multi_user/knowledge_access.py b/deeptutor/multi_user/knowledge_access.pyindex 83e67a2fd..bb4c84a49 100644--- a/deeptutor/multi_user/knowledge_access.py+++ b/deeptutor/multi_user/knowledge_access.py@@ -4,12 +4,13 @@ from __future__ import annotationsfrom functools import lru_cachefrom pathlib import Path-from typing import Any+from typing import TYPE_CHECKING, Any-from fastapi import HTTPException+if TYPE_CHECKING:+ from deeptutor.knowledge.manager import KnowledgeBaseManager+from deeptutor.core.errors import AccessErrorfrom deeptutor.knowledge.kb_types import SUBAGENT_KB_TYPE-from deeptutor.knowledge.manager import KnowledgeBaseManagerfrom deeptutor.knowledge.manifest import (MANIFEST_NOTE_LIMIT,KbManifest,@@ -29,6 +30,11 @@ DEFAULT_KB_ALIASES = {"", "default", "current", "selected", "默认", "默认知@lru_cache(maxsize=128)def _manager_for(base_dir: str) -> KnowledgeBaseManager:+ from deeptutor.modules.catalog import require_module++ require_module("knowledge")+ from deeptutor.knowledge.manager import KnowledgeBaseManager+return KnowledgeBaseManager(base_dir=base_dir)@@ -131,9 +137,9 @@ def _resolve_kb(kb_ref: str, *, require_write: bool = False) -> KnowledgeResourcif requested_source == "admin":if name not in assigned_names:- raise HTTPException(status_code=403, detail="Knowledge base is not assigned to you")+ raise AccessError(status_code=403, detail="Knowledge base is not assigned to you")if require_write:- raise HTTPException(+ raise AccessError(status_code=403, detail="Assigned admin knowledge bases are read-only")return KnowledgeResource(@@ -180,7 +186,7 @@ def _resolve_kb(kb_ref: str, *, require_write: bool = False) -> KnowledgeResourcif name in assigned_names:if require_write:- raise HTTPException(+ raise AccessError(status_code=403, detail="Assigned admin knowledge bases are read-only")return KnowledgeResource(@@ -192,7 +198,7 @@ def _resolve_kb(kb_ref: str, *, require_write: bool = False) -> KnowledgeResourcread_only=True,)- raise HTTPException(status_code=404, detail=f"Knowledge base '{name}' not found")+ raise AccessError(status_code=404, detail=f"Knowledge base '{name}' not found")def _resolve_default_or_name(manager: KnowledgeBaseManager, name: str) -> str:@@ -204,8 +210,8 @@ def _resolve_default_or_name(manager: KnowledgeBaseManager, name: str) -> str:default_kb = manager.get_default()if default_kb and default_kb in names:return default_kb- raise HTTPException(status_code=404, detail="No default knowledge base is configured")- raise HTTPException(status_code=404, detail=f"Knowledge base '{requested}' not found")+ raise AccessError(status_code=404, detail="No default knowledge base is configured")+ raise AccessError(status_code=404, detail=f"Knowledge base '{requested}' not found")def manager_for_resource(resource: KnowledgeResource) -> KnowledgeBaseManager:@@ -361,7 +367,7 @@ def resolve_kb_metadata(kb_ref: str | None) -> dict[str, Any] | None:return Nonetry:resource = resolve_kb(str(kb_ref), require_write=False)- except HTTPException:+ except AccessError:return Nonemanager = _manager_for(str(resource.base_dir.resolve()))return manager.get_metadata(resource.name)@@ -385,7 +391,7 @@ def resolve_kb_manifest(return Nonetry:resource = resolve_kb(str(kb_ref), require_write=False)- except HTTPException:+ except AccessError:return Nonemanager = _manager_for(str(resource.base_dir.resolve()))entry = manager.get_kb_entry(resource.name)@@ -418,7 +424,7 @@ def resolve_kb_document_path(kb_ref: str | None, rel_path: str) -> Path | None:return Nonetry:resource = resolve_kb(str(kb_ref), require_write=False)- except HTTPException:+ except AccessError:return Nonemanager = _manager_for(str(resource.base_dir.resolve()))entry = manager.get_kb_entry(resource.name)diff --git a/deeptutor/multi_user/partner_access.py b/deeptutor/multi_user/partner_access.pyindex 7966c0cae..5c0bc60fd 100644--- a/deeptutor/multi_user/partner_access.py+++ b/deeptutor/multi_user/partner_access.py@@ -25,7 +25,7 @@ from __future__ import annotationsfrom typing import Any-from fastapi import HTTPException+from deeptutor.core.errors import AccessErrorfrom .context import get_current_userfrom .grants import load_grant@@ -88,7 +88,7 @@ def assert_partner_allowed(partner_id: str, user_id: str | None = None) -> None:returnif str(partner_id or "").strip() in assigned_partner_ids(user_id or user.id):return- raise HTTPException(status_code=403, detail="Partner is not assigned to you")+ raise AccessError(status_code=403, detail="Partner is not assigned to you")def assert_partner_manageable(partner_id: str) -> None:@@ -98,7 +98,7 @@ def assert_partner_manageable(partner_id: str) -> None:talk to a partner learns nothing new about who owns it."""if not can_manage_partner(partner_id):- raise HTTPException(status_code=403, detail="You cannot manage this partner")+ raise AccessError(status_code=403, detail="You cannot manage this partner")# Identity-only card fields a consumer needs (partner list page, connect modal).@@ -133,6 +133,10 @@ def visible_partners() -> list[dict[str, Any]]:so it doesn't have to re-derive ownership."""user = get_current_user()+ from deeptutor.modules.catalog import module_enabled++ if not module_enabled("partners"):+ return []out: list[dict[str, Any]] = []for partner in _manager().list_partners():pid = str(partner.get("partner_id") or "")diff --git a/deeptutor/multi_user/paths.py b/deeptutor/multi_user/paths.pyindex 036d56616..de7936834 100644--- a/deeptutor/multi_user/paths.py+++ b/deeptutor/multi_user/paths.py@@ -179,7 +179,7 @@ def _resolve_owner() -> tuple[str, PathService]:"give up and assume admin" fallback fails open onto the most privilegedaccount there is)."""- from deeptutor.services.partners.scope import is_partner_user_id+ from deeptutor.core.identities import is_partner_user_idfrom .context import get_current_user_or_nonediff --git a/deeptutor/multi_user/skill_access.py b/deeptutor/multi_user/skill_access.pyindex 91318122c..598c6c6bb 100644--- a/deeptutor/multi_user/skill_access.py+++ b/deeptutor/multi_user/skill_access.py@@ -4,8 +4,6 @@ from __future__ import annotationsfrom typing import Any-from fastapi import HTTPException-from .context import get_current_userfrom .grants import load_grant@@ -71,4 +69,6 @@ def assert_skill_allowed(name: str) -> None:if user.is_admin:returnif name not in assigned_skill_ids(user.id):- raise HTTPException(status_code=403, detail="Skill is not assigned to you")+ from deeptutor.core.errors import AccessError++ raise AccessError(status_code=403, detail="Skill is not assigned to you")diff --git a/deeptutor/partners/helpers.py b/deeptutor/partners/helpers.pyindex 67cfa47a7..3d6f68e9c 100644--- a/deeptutor/partners/helpers.py+++ b/deeptutor/partners/helpers.py@@ -4,6 +4,8 @@ from datetime import datetimefrom pathlib import Pathimport re+from deeptutor.utils.filenames import safe_filename as safe_filename+def detect_image_mime(data: bytes) -> str | None:"""Detect image MIME type from magic bytes, ignoring file extension."""@@ -29,16 +31,6 @@ def timestamp() -> str:return datetime.now().isoformat()-_UNSAFE_CHARS = re.compile(r'[<>:"/\\|?*]')-_CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f]")---def safe_filename(name: str) -> str:- """Replace unsafe path / control characters; ``.`` / ``..`` become empty."""- cleaned = _CONTROL_CHARS.sub("", _UNSAFE_CHARS.sub("_", name or "")).strip().strip(".")- return cleaned--def split_message(content: str, max_len: int = 2000) -> list[str]:"""Split content into chunks within max_len, preferring line breaks.diff --git a/deeptutor/plugins/runtime.py b/deeptutor/plugins/runtime.pyindex ad5dbf22f..2082dc713 100644--- a/deeptutor/plugins/runtime.py+++ b/deeptutor/plugins/runtime.py@@ -3,6 +3,7 @@from __future__ import annotationsimport asyncio+from contextvars import ContextVarfrom dataclasses import asdict, dataclassimport jsonimport logging@@ -10,6 +11,8 @@ import osfrom pathlib import Pathimport reimport subprocess+import threading+import timefrom typing import Any, Mappingfrom deeptutor.core.capability_protocol import (@@ -36,6 +39,9 @@ from deeptutor.plugins.registry import ()logger = logging.getLogger(__name__)+_worker_cancellation: ContextVar[threading.Event | None] = ContextVar(+ "worker_cancellation", default=None+)class PluginRuntimeError(RuntimeError):@@ -101,6 +107,112 @@ class _WorkerClient:self.validate_permissions(response.get("permissions"))return response+ async def request_async(self, operation: str, payload: dict[str, Any]):+ """Legacy buffered workers also stop when their owning turn is cancelled."""+ cancelled = threading.Event()+ token = _worker_cancellation.set(cancelled)+ task = asyncio.create_task(asyncio.to_thread(self.request, operation, payload))+ _worker_cancellation.reset(token)+ try:+ return await asyncio.shield(task)+ except asyncio.CancelledError:+ cancelled.set()+ await asyncio.gather(task, return_exceptions=True)+ raise++ async def stream(self, operation: str, payload: dict[str, Any]):+ """NDJSON v1: bounded live events, explicit completion and process cleanup."""++ if self.guard is not None:+ self.guard()+ encoded = json.dumps(+ {"operation": operation, "transport": "ndjson-v1", **payload},+ ensure_ascii=False,+ default=str,+ ).encode()+ if len(encoded) > 1024 * 1024:+ raise PluginRuntimeError("Plugin worker request exceeds 1 MiB.")+ process = await asyncio.create_subprocess_exec(+ str(self.python_path),+ "-m",+ self.module,+ stdin=asyncio.subprocess.PIPE,+ stdout=asyncio.subprocess.PIPE,+ stderr=asyncio.subprocess.PIPE,+ env=_clean_env(),+ cwd=self.venv_path,+ start_new_session=os.name != "nt",+ limit=1024 * 1024,+ )+ stderr = bytearray()++ async def drain_errors():+ while chunk := await process.stderr.read(8192):+ stderr.extend(chunk)+ if len(stderr) > 65536:+ raise PluginRuntimeError("Plugin worker stderr exceeds 64 KiB.")++ async def produce():+ process.stdin.write(encoded)+ await process.stdin.drain()+ process.stdin.close()+ total = 0+ completed = False+ while line := await process.stdout.readline():+ total += len(line)+ if total > 16 * 1024 * 1024:+ raise PluginRuntimeError("Plugin worker stream exceeds 16 MiB.")+ if self.guard is not None:+ self.guard()+ try:+ row = json.loads(line)+ except (ValueError, UnicodeError) as exc:+ raise PluginRuntimeError("Plugin worker returned invalid NDJSON.") from exc+ if not isinstance(row, dict) or completed:+ raise PluginRuntimeError("Invalid plugin stream envelope/order.")+ self.validate_permissions(row.get("permissions"))+ if row.get("error") is not None:+ raise PluginRuntimeError(str(row["error"])[-2000:])+ if row.get("kind") == "complete":+ completed = True+ elif row.get("kind") == "event" and isinstance(row.get("event"), dict):+ await queue.put(row["event"])+ else:+ raise PluginRuntimeError("Unknown plugin stream envelope.")+ code = await process.wait()+ if code or not completed:+ raise PluginRuntimeError(+ f"Plugin stream ended without successful completion ({code}): "+ + stderr.decode("utf-8", "replace")[-2000:]+ )++ queue: asyncio.Queue = asyncio.Queue(maxsize=64)++ async def run():+ try:+ async with asyncio.timeout(300):+ async with asyncio.TaskGroup() as group:+ group.create_task(drain_errors())+ group.create_task(produce())+ finally:+ # Wake the consumer even when the worker fails with an empty stream.+ if not asyncio.current_task().cancelling():+ await queue.put(None)++ task = asyncio.create_task(run())+ try:+ while (item := await queue.get()) is not None:+ yield item+ await task+ finally:+ task.cancel()+ # Kill the entire session, including render helpers inheriting pipes.+ from deeptutor.runtime.process import kill_process_tree++ await asyncio.to_thread(kill_process_tree, process.pid)+ await process.wait()+ await asyncio.gather(task, return_exceptions=True)+def validate_permissions(self, raw: Any) -> None:if raw is None:return@@ -145,9 +257,7 @@ class PluginWorkerTool(BaseTool):return self._definitionasync def execute(self, **kwargs: Any) -> ToolResult:- response = await asyncio.to_thread(- self._client.request, "execute_tool", {"arguments": kwargs}- )+ response = await self._client.request_async("execute_tool", {"arguments": kwargs})result = response.get("result")if not isinstance(result, dict):raise PluginRuntimeError("execute_tool response requires a result object")@@ -226,6 +336,7 @@ class PluginWorkerCapability(TurnCapability):guard=_managed_guard(manifest, installation, registry),)described = self._client.request("describe_capability")+ self._streaming = described.get("transport") == "ndjson-v1"raw = described.get("capability")if not isinstance(raw, dict) or raw.get("name") != extension_id:raise PluginRuntimeError(@@ -245,24 +356,25 @@ class PluginWorkerCapability(TurnCapability):return PluginWorkerCapability(**self._clone_args)async def run(self, context: UnifiedContext, stream: StreamBusProtocol) -> None:- response = await asyncio.to_thread(- self._client.request,- "run_capability",- {- "context": {- "session_id": context.session_id,- "user_message": context.user_message,- "conversation_history": context.conversation_history,- "enabled_tools": context.enabled_tools,- "active_capability": context.active_capability,- "knowledge_bases": context.knowledge_bases,- "attachments": [asdict(item) for item in context.attachments],- "config_overrides": context.config_overrides,- "language": context.language,- "metadata": context.metadata,- }- },- )+ payload = {+ "context": {+ "session_id": context.session_id,+ "user_message": context.user_message,+ "conversation_history": context.conversation_history,+ "enabled_tools": context.enabled_tools,+ "active_capability": context.active_capability,+ "knowledge_bases": context.knowledge_bases,+ "attachments": [asdict(item) for item in context.attachments],+ "config_overrides": context.config_overrides,+ "language": context.language,+ "metadata": context.metadata,+ }+ }+ if self._streaming:+ async for raw in self._client.stream("run_capability", payload):+ await stream.emit(_stream_event(raw, source=self.manifest.name))+ return+ response = await self._client.request_async("run_capability", payload)events = response.get("events", [])if not isinstance(events, list):raise PluginRuntimeError("run_capability events must be an array")@@ -607,7 +719,6 @@ def _managed_guard(manifest, installation, registry=None):def _run_worker(argv, *, input, env, cwd):"""Bound both worker time and captured output, without blocking the event loop."""- import signalimport threadingfrom types import SimpleNamespace@@ -627,13 +738,9 @@ def _run_worker(argv, *, input, env, cwd):overflow = threading.Event()def stop():- try:- if os.name != "nt":- os.killpg(process.pid, signal.SIGKILL)- else:- process.kill()- except ProcessLookupError:- pass+ from deeptutor.runtime.process import kill_process_tree++ kill_process_tree(process.pid)def read(name, pipe, limit):while chunk := pipe.read(8192):@@ -660,7 +767,19 @@ def _run_worker(argv, *, input, env, cwd):for thread in threads:thread.start()try:- process.wait(timeout=60)+ deadline = time.monotonic() + 60+ cancelled = _worker_cancellation.get()+ while True:+ if cancelled is not None and cancelled.is_set():+ raise PluginRuntimeError("Plugin worker cancelled.")+ remaining = deadline - time.monotonic()+ if remaining <= 0:+ raise subprocess.TimeoutExpired(argv, 60)+ try:+ process.wait(timeout=min(remaining, 0.1))+ break+ except subprocess.TimeoutExpired:+ continueexcept BaseException:stop()process.wait(timeout=3)diff --git a/deeptutor/runtime/bootstrap/builtin_capabilities.py b/deeptutor/runtime/bootstrap/builtin_capabilities.pyindex 6cccf5137..eef33ea56 100644--- a/deeptutor/runtime/bootstrap/builtin_capabilities.py+++ b/deeptutor/runtime/bootstrap/builtin_capabilities.py@@ -1,10 +1,11 @@-"""Import-free descriptors for built-in turn capabilities."""+"""Compatibility view of module-owned, import-free capability declarations."""from __future__ import annotationsfrom dataclasses import dataclassfrom deeptutor.core.capability_protocol import CapabilityManifest+from deeptutor.modules.catalog import manifests@dataclass(frozen=True, slots=True)@@ -13,242 +14,35 @@ class BuiltinCapabilitySpec:manifest: CapabilityManifest-def _manifest(- name: str,- description: str,- *,- stages: list[str],- tools_used: list[str],- cli_aliases: list[str],- config_defaults: dict[str, object] | None = None,-) -> CapabilityManifest:- return CapabilityManifest(- name=name,- description=description,- stages=stages,- tools_used=tools_used,- cli_aliases=cli_aliases,- config_defaults=config_defaults or {},+BUILTIN_CAPABILITY_SPECS = {+ name: BuiltinCapabilitySpec(spec["class_path"], CapabilityManifest(**spec["manifest"]))+ for name, spec in sorted(+ (+ (name, spec)+ for module in manifests().values()+ for name, spec in module["capabilities"].items()+ ),+ key=lambda row: row[1]["order"],)+}+BUILTIN_CAPABILITY_CLASSES = {+ name: spec.class_path for name, spec in BUILTIN_CAPABILITY_SPECS.items()+}-BUILTIN_CAPABILITY_CLASSES: dict[str, str] = {- "chat": "deeptutor.agents.chat.capability:ChatCapability",- "ask_questions": ("deeptutor.capabilities.ask_questions.capability:AskQuestionsCapability"),- "deep_solve": "deeptutor.capabilities.solve.capability:DeepSolveCapability",- "deep_question": "deeptutor.agents.question.capability:DeepQuestionCapability",- "deep_research": "deeptutor.agents.research.capability:DeepResearchCapability",- "math_animator": "deeptutor.agents.math_animator.capability:MathAnimatorCapability",- "video_lesson": "deeptutor.agents.video_lesson.capability:VideoLessonCapability",- "visualize": "deeptutor.agents.visualize.capability:VisualizeCapability",- "mastery_path": "deeptutor.capabilities.mastery.capability:MasteryPathCapability",- "immersive_reading": "deeptutor.capabilities.reading.mode:ImmersiveReadingCapability",- "audio_overview": ("deeptutor.capabilities.audio_overview.capability:AudioOverviewCapability"),-}+def builtin_capability_manifest(name: str) -> CapabilityManifest:+ from dataclasses import replace+ from deeptutor.runtime.request_contracts import get_capability_request_schema-BUILTIN_CAPABILITY_SPECS: dict[str, BuiltinCapabilitySpec] = {- "chat": BuiltinCapabilitySpec(- BUILTIN_CAPABILITY_CLASSES["chat"],- _manifest(- "chat",- "Agentic chat: an exploring agent loop with tools, followed by a respond stage that streams the answer.",- stages=["exploring", "responding"],- tools_used=[- "brainstorm",- "web_search",- "paper_search",- "zotero_search",- "reason",- "geogebra_analysis",- "imagegen",- "videogen",- ],- cli_aliases=["chat"],- ),- ),- "ask_questions": BuiltinCapabilitySpec(- BUILTIN_CAPABILITY_CLASSES["ask_questions"],- _manifest(- "ask_questions",- "Ask the user high-value questions to fill in missing context, then complete the original request with their answers.",- stages=["responding"],- tools_used=["ask_user"],- cli_aliases=["ask"],- ),- ),- "deep_solve": BuiltinCapabilitySpec(- BUILTIN_CAPABILITY_CLASSES["deep_solve"],- _manifest(- "deep_solve",- "Multi-step problem solving driven by the chat agent loop.",- stages=["responding"],- tools_used=[- "solve_plan",- "solve_finish_step",- "solve_replan",- "rag",- "exec",- "geogebra_analysis",- "reason",- ],- cli_aliases=["solve"],- ),- ),- "deep_question": BuiltinCapabilitySpec(- BUILTIN_CAPABILITY_CLASSES["deep_question"],- _manifest(- "deep_question",- "Fast question generation (Template batches -> Generate).",- stages=["ideation", "generation"],- tools_used=["rag", "web_search", "exec"],- cli_aliases=["quiz"],- ),- ),- "deep_research": BuiltinCapabilitySpec(- BUILTIN_CAPABILITY_CLASSES["deep_research"],- _manifest(- "deep_research",- "Agentic-loop deep research with iterative report generation.",- stages=["rephrasing", "decomposing", "researching", "reporting"],- tools_used=[- "rag",- "web_search",- "paper_search",- "preprint",- "research_audit",- "research_lit",- "exec",- ],- cli_aliases=["research"],- ),- ),- "math_animator": BuiltinCapabilitySpec(- BUILTIN_CAPABILITY_CLASSES["math_animator"],- _manifest(- "math_animator",- "Generate math animations or storyboard images with Manim.",- stages=[- "concept_analysis",- "concept_design",- "code_generation",- "code_retry",- "summary",- "render_output",- ],- tools_used=[],- cli_aliases=["animate"],- config_defaults={- "output_mode": "video",- "quality": "medium",- "style_hint": "",- },- ),- ),- "video_lesson": BuiltinCapabilitySpec(- BUILTIN_CAPABILITY_CLASSES["video_lesson"],- _manifest(- "video_lesson",- "Generate an animated video lesson (Remotion) that plays in the browser.",- stages=["code_generation", "render_check", "render_output"],- tools_used=[],- cli_aliases=["lesson"],- ),- ),- "visualize": BuiltinCapabilitySpec(- BUILTIN_CAPABILITY_CLASSES["visualize"],- _manifest(- "visualize",- "Generate a validated visualization with any installed visualizer type, or render a Manim animation/storyboard artifact.",- stages=[- "analyzing",- "generating",- "reviewing",- "concept_analysis",- "concept_design",- "code_generation",- "code_retry",- "summary",- "render_output",- ],- tools_used=["submit_visualization"],- cli_aliases=["visualize", "viz"],- ),- ),- "mastery_path": BuiltinCapabilitySpec(- BUILTIN_CAPABILITY_CLASSES["mastery_path"],- _manifest(- "mastery_path",- "Mastery-based tutoring: a dedicated agent loop drives an adaptive mastery path with a hard, per-type mastery gate and spaced review.",- stages=["responding"],- tools_used=[- "mastery_prepare_lesson",- "mastery_status",- "mastery_quiz",- "mastery_note_explained",- "mastery_grade",- "mastery_skip_question",- "mastery_repair_question",- "mastery_defer_objective",- "mastery_assess",- "mastery_build",- "mastery_mode",- "mastery_profile",- "mastery_revise",- "mastery_paths",- "mastery_switch",- "mastery_leave",- "rag",- "read_source",- "ask_user",- ],- cli_aliases=["mastery"],- ),- ),- "immersive_reading": BuiltinCapabilitySpec(- BUILTIN_CAPABILITY_CLASSES["immersive_reading"],- _manifest(- "immersive_reading",- "Read a document alongside the assistant, which cites the exact page or section behind every claim.",- stages=["responding"],- tools_used=[- "reading_list_tabs",- "reading_switch_tab",- "material_outline",- "search_material",- "read_material",- "view_figure",- "reader_goto",- "reader_annotate",- "web_search",- "exec",- "reason",- ],- cli_aliases=["reading", "read"],- ),- ),- "audio_overview": BuiltinCapabilitySpec(- BUILTIN_CAPABILITY_CLASSES["audio_overview"],- _manifest(- "audio_overview",- "Create a grounded two-voice audio overview and transcript from a knowledge base.",- stages=["retrieving", "script_writing", "voice_generation", "publishing"],- tools_used=["rag"],- cli_aliases=["audio-overview", "overview"],- config_defaults={- "topic": "",- "target_minutes": 5,- "host_voice": None,- "expert_voice": None,- "max_context_chunks": 6,- },- ),- ),-}+ return replace(+ BUILTIN_CAPABILITY_SPECS[name].manifest, request_schema=get_capability_request_schema(name)+ )__all__ = [- "BUILTIN_CAPABILITY_CLASSES","BUILTIN_CAPABILITY_SPECS",+ "BUILTIN_CAPABILITY_CLASSES","BuiltinCapabilitySpec",+ "builtin_capability_manifest",]diff --git a/deeptutor/runtime/orchestrator.py b/deeptutor/runtime/orchestrator.pyindex 6c0b504f9..2105d1cc8 100644--- a/deeptutor/runtime/orchestrator.py+++ b/deeptutor/runtime/orchestrator.py@@ -71,11 +71,15 @@ class ChatOrchestrator:context.session_id = str(uuid.uuid4())try:- from deeptutor.services.rag.pipelines.pageindex import (- validate_pageindex_oss_selection,- )+ if context.knowledge_bases:+ from deeptutor.modules.catalog import require_module++ require_module("knowledge")+ from deeptutor.services.rag.pipelines.pageindex import (+ validate_pageindex_oss_selection,+ )- validate_pageindex_oss_selection(context.knowledge_bases)+ validate_pageindex_oss_selection(context.knowledge_bases)except ValueError as exc:bus = StreamBus()await bus.error(diff --git a/deeptutor/runtime/process.py b/deeptutor/runtime/process.pyindex 35c9ac0cd..b64380227 100644--- a/deeptutor/runtime/process.py+++ b/deeptutor/runtime/process.py@@ -1,8 +1,34 @@-"""Cross-platform process liveness checks with no process-side effects."""+"""Cross-platform liveness checks and cleanup of owned subprocess trees."""from __future__ import annotationsimport os+import signal+import subprocess+++def kill_process_tree(pid: int) -> None:+ """Kill an owned child (started in a new POSIX session) and its helpers.++ Callers still reap their process/streams before releasing runtime leases.+ Windows Process.kill() alone leaves build and renderer children running.+ """+ if os.name != "nt":+ try:+ os.killpg(pid, signal.SIGKILL)+ except ProcessLookupError:+ pass+ return+ result = subprocess.run(+ ["taskkill", "/PID", str(pid), "/T", "/F"],+ stdout=subprocess.DEVNULL,+ stderr=subprocess.DEVNULL,+ timeout=10,+ check=False,+ creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),+ )+ if result.returncode not in (0, 128):+ raise RuntimeError(f"Could not terminate process tree {pid}: {result.returncode}")def _is_windows_process_alive(pid: int) -> bool:@@ -48,4 +74,4 @@ def is_process_alive(pid: int | None) -> bool:return True-__all__ = ["is_process_alive"]+__all__ = ["is_process_alive", "kill_process_tree"]diff --git a/deeptutor/runtime/registry/capability_registry.py b/deeptutor/runtime/registry/capability_registry.pyindex 9ed3b7798..2f4f9faaa 100644--- a/deeptutor/runtime/registry/capability_registry.py+++ b/deeptutor/runtime/registry/capability_registry.py@@ -12,6 +12,7 @@ from pydantic import BaseModelfrom deeptutor.core.capability_protocol import TurnCapabilityfrom deeptutor.i18n.metadata_i18n import capability_description_i18n+from deeptutor.modules.catalog import contribution_enabledfrom deeptutor.plugins.entry_points import load_entry_point_groupfrom deeptutor.runtime.bootstrap.builtin_capabilities import BUILTIN_CAPABILITY_SPECSfrom deeptutor.runtime.capability_catalog import (@@ -83,6 +84,8 @@ class CapabilityRegistry:def load_builtins(self) -> None:for name, spec in BUILTIN_CAPABILITY_SPECS.items():+ if not contribution_enabled("capabilities", name):+ continueif self.catalog.get("turn", name) is not None:continueclass_path = spec.class_path@@ -142,6 +145,8 @@ class CapabilityRegistry:logger.debug("Legacy plugin loader unavailable", exc_info=True)def get(self, name: str) -> TurnCapability | None:+ if not contribution_enabled("capabilities", name):+ return Noneif name not in BUILTIN_CAPABILITY_SPECS:from deeptutor.plugins.registry import PluginRegistryfrom deeptutor.plugins.runtime import PluginWorkerCapability, runtime_plugin_records@@ -190,7 +195,8 @@ class CapabilityRegistry:"config_defaults": entry.manifest.config_defaults,}for entry in self.catalog.entries("turn")- if getattr(entry.factory, "_plugin_allowed", lambda: True)()+ if contribution_enabled("capabilities", entry.name)+ and getattr(entry.factory, "_plugin_allowed", lambda: True)()]from deeptutor.plugins.runtime import runtime_plugin_recordsdiff --git a/deeptutor/runtime/registry/tool_registry.py b/deeptutor/runtime/registry/tool_registry.pyindex 6537eacd2..c6cc92a35 100644--- a/deeptutor/runtime/registry/tool_registry.py+++ b/deeptutor/runtime/registry/tool_registry.py@@ -13,6 +13,7 @@ import loggingfrom typing import Anyfrom deeptutor.core.tool_protocol import BaseTool, ToolDefinition, ToolPromptHints+from deeptutor.modules.catalog import contribution_enabledfrom deeptutor.plugins.entry_points import load_entry_point_groupfrom deeptutor.tools.builtin_specs import (BUILTIN_TOOL_NAMES,@@ -118,11 +119,20 @@ class ToolRegistry:def get(self, name: str) -> BaseTool | None:resolved_name, _ = self._resolve_request(name)+ if not contribution_enabled("tools", resolved_name):+ return Nonereturn self._tools.get(resolved_name) or self._load_builtin(resolved_name)def list_tools(self) -> list[str]:builtin = [name for name in BUILTIN_TOOL_NAMES if name in self._builtin_specs]- return [*builtin, *(name for name in self._tools if name not in self._builtin_specs)]+ return [+ name+ for name in [+ *builtin,+ *(name for name in self._tools if name not in self._builtin_specs),+ ]+ if contribution_enabled("tools", name)+ ]def get_enabled(self, names: list[str]) -> list[BaseTool]:"""Return tool instances for the given names (skipping unknown)."""@@ -181,7 +191,7 @@ class ToolRegistry:positionally."""resolved_name, resolved_kwargs = self._resolve_request(name, kwargs)- tool = self._tools.get(resolved_name) or self._load_builtin(resolved_name)+ tool = self.get(resolved_name)if tool is None:raise KeyError(f"Unknown tool: {name}")return await tool.execute(**resolved_kwargs)diff --git a/deeptutor/runtime/request_contracts.py b/deeptutor/runtime/request_contracts.pyindex ae78e0099..3efc3c9a6 100644--- a/deeptutor/runtime/request_contracts.py+++ b/deeptutor/runtime/request_contracts.py@@ -2,21 +2,13 @@from __future__ import annotations-from typing import Any, Callable, Literal+from collections.abc import Mapping+from importlib import import_module+from typing import Any, Literalfrom pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator-from deeptutor.agents.math_animator.request_config import (- MathAnimatorRequestConfig,- validate_math_animator_request_config,-)-from deeptutor.agents.research.request_config import (- DeepResearchRequestConfig,- validate_research_request_config,-)-from deeptutor.capabilities.audio_overview.request_config import (- AudioOverviewRequestConfig,-)+from deeptutor.modules.catalog import contribution_enabled, manifestsfrom deeptutor.runtime.capability_catalog import EmptyConfig@@ -138,54 +130,59 @@ def build_request_schema(model_type: type[BaseModel]) -> dict[str, Any]:return model_type.model_json_schema(mode="validation")-CAPABILITY_CONFIG_VALIDATORS: dict[str, Callable[[dict[str, Any] | None], Any]] = {- "chat": validate_chat_request_config,- "deep_solve": validate_deep_solve_request_config,- "deep_question": validate_deep_question_request_config,- "deep_research": validate_research_request_config,- "math_animator": validate_math_animator_request_config,- "visualize": validate_visualize_request_config,-}--CAPABILITY_CONFIG_MODELS: dict[str, type[BaseModel]] = {- "audio_overview": AudioOverviewRequestConfig,- "chat": ChatRequestConfig,- "ask_questions": AskQuestionsRequestConfig,- "deep_solve": DeepSolveRequestConfig,- "deep_question": DeepQuestionRequestConfig,- "deep_research": DeepResearchRequestConfig,- "math_animator": MathAnimatorRequestConfig,- "visualize": VisualizeRequestConfig,- "mastery_path": MasteryPathRequestConfig,- "immersive_reading": ImmersiveReadingRequestConfig,- "video_lesson": VideoLessonRequestConfig,-}---def _model_validator(- model_type: type[BaseModel],- capability_name: str,-) -> Callable[[dict[str, Any] | None], BaseModel]:- def validate(raw_config: dict[str, Any] | None) -> BaseModel:- return _validate_model(- model_type,- raw_config,- label=capability_name.replace("_", " "),- )-- return validate+class _Contracts(Mapping):+ def __init__(self, kind: str):+ self.kind = kind+ def __iter__(self):+ return iter(+ name+ for module in manifests().values()+ for name in module["capabilities"]+ if contribution_enabled("capabilities", name)+ )-# Every built-in has an explicit validator, including no-options capabilities.-for _capability_name, _model_type in CAPABILITY_CONFIG_MODELS.items():- CAPABILITY_CONFIG_VALIDATORS.setdefault(- _capability_name,- _model_validator(_model_type, _capability_name),- )--CAPABILITY_REQUEST_SCHEMAS: dict[str, dict[str, Any]] = {- name: build_request_schema(model_type) for name, model_type in CAPABILITY_CONFIG_MODELS.items()-}+ def __len__(self):+ return sum(1 for _ in self)++ def __getitem__(self, name):+ if not contribution_enabled("capabilities", name):+ raise KeyError(name)+ spec = next(+ (+ module["capabilities"][name]+ for module in manifests().values()+ if name in module["capabilities"]+ ),+ None,+ )+ if spec is None:+ raise KeyError(name)+ module, attribute = spec["config_model"].split(":")+ model = getattr(import_module(module), attribute)+ if self.kind == "models":+ return model+ if self.kind == "schemas":+ return build_request_schema(model)+ if "validator" in spec:+ reference, attribute = spec["validator"].split(":")+ return getattr(import_module(reference), attribute)+ return lambda raw: _validate_model(model, raw, label=name.replace("_", " "))+++CAPABILITY_CONFIG_MODELS = _Contracts("models")+CAPABILITY_CONFIG_VALIDATORS = _Contracts("validators")+CAPABILITY_REQUEST_SCHEMAS = _Contracts("schemas")+++def __getattr__(name: str):+ # Preserve imports used by SDK clients while leaving absent modules cold.+ for module in manifests().values():+ for spec in module["capabilities"].values():+ reference, attribute = spec["config_model"].split(":")+ if attribute == name and reference != __name__:+ return getattr(import_module(reference), attribute)+ raise AttributeError(name)def validate_capability_config(@@ -208,7 +205,7 @@ __all__ = ["CAPABILITY_CONFIG_VALIDATORS","CAPABILITY_CONFIG_MODELS","CAPABILITY_REQUEST_SCHEMAS",- "AudioOverviewRequestConfig",+ "AudioOverviewRequestConfig", # noqa: F822 - lazy compatibility export"AskQuestionsRequestConfig","ChatRequestConfig","DeepQuestionRequestConfig",diff --git a/deeptutor/services/calendar/layers.py b/deeptutor/services/calendar/layers.pyindex c18c6b2b3..4f2085810 100644--- a/deeptutor/services/calendar/layers.py+++ b/deeptutor/services/calendar/layers.py@@ -24,9 +24,7 @@ def owner_key():def read_layers(workspace_id, start, end, tzid):- from deeptutor.learning.policy import path_display_name- from deeptutor.learning.scheduler import SpacedRepetitionScheduler- from deeptutor.learning.storage import LearningStore+ from deeptutor.modules.catalog import module_enabledfrom deeptutor.services.cron.service import compute_next_run, get_cron_servicefrom deeptutor.services.practice.storage import _DUE_AT_SQL, PracticeStorefrom deeptutor.services.session import get_sqlite_session_store@@ -47,26 +45,33 @@ def read_layers(workspace_id, start, end, tzid):key = day(ts)return footprints.setdefault(key, FootprintDay(date=key))- learning = LearningStore()- scheduler = SpacedRepetitionScheduler()- for progress, _topic, _count, _interaction in learning.list_topic_snapshots():- counts = {}- for task in scheduler.build_review_queue(progress):- if lo <= task.due_at < hi:- key = day(task.due_at)- counts[key] = counts.get(key, 0) + 1- for key, count in counts.items():- row = reviews.setdefault(key, ReviewDay(date=key))- row.mastery += count- row.paths.append(- ReviewPathCount(id=progress.book_id, title=path_display_name(progress), count=count)- )- with learning._connect() as db:- for row in db.execute(- "SELECT timestamp FROM mastery_learning_evidence WHERE timestamp>=? AND timestamp<?",- (lo, hi),- ):- footprint(row[0]).mastery_evidence += 1+ if module_enabled("mastery"):+ from deeptutor.learning.policy import path_display_name+ from deeptutor.learning.scheduler import SpacedRepetitionScheduler+ from deeptutor.learning.storage import LearningStore++ learning = LearningStore()+ scheduler = SpacedRepetitionScheduler()+ for progress, _topic, _count, _interaction in learning.list_topic_snapshots():+ counts = {}+ for task in scheduler.build_review_queue(progress):+ if lo <= task.due_at < hi:+ key = day(task.due_at)+ counts[key] = counts.get(key, 0) + 1+ for key, count in counts.items():+ row = reviews.setdefault(key, ReviewDay(date=key))+ row.mastery += count+ row.paths.append(+ ReviewPathCount(+ id=progress.book_id, title=path_display_name(progress), count=count+ )+ )+ with learning._connect() as db:+ for row in db.execute(+ "SELECT timestamp FROM mastery_learning_evidence WHERE timestamp>=? AND timestamp<?",+ (lo, hi),+ ):+ footprint(row[0]).mastery_evidence += 1practice = PracticeStore(get_sqlite_session_store().db_path)# The database is already workspace-scoped; match PracticeStore’s live-entry filter.diff --git a/deeptutor/services/config/__init__.py b/deeptutor/services/config/__init__.pyindex eaea44e84..a3939d927 100644--- a/deeptutor/services/config/__init__.py+++ b/deeptutor/services/config/__init__.py@@ -2,10 +2,6 @@import importlib-from .knowledge_base_config import (- KnowledgeBaseConfigService,- get_kb_config_service,-)from .launch_settings import LaunchSettings, load_launch_settingsfrom .loader import (DEFAULT_CHAT_PARAMS,@@ -140,6 +136,9 @@ def __getattr__(name: str):provider_runtime = importlib.import_module(f"{__name__}.provider_runtime")return getattr(provider_runtime, name)+ if name in {"KnowledgeBaseConfigService", "get_kb_config_service"}:+ module = importlib.import_module(f"{__name__}.knowledge_base_config")+ return getattr(module, name)if name in {"ConfigTestRunner", "TestRun", "get_config_test_runner"}:test_runner = importlib.import_module(f"{__name__}.test_runner")return getattr(test_runner, name)diff --git a/deeptutor/services/config/readiness.py b/deeptutor/services/config/readiness.pyindex c648a49b6..28efe8f83 100644--- a/deeptutor/services/config/readiness.py+++ b/deeptutor/services/config/readiness.py@@ -883,16 +883,13 @@ def _module_available(name: str) -> bool:async def build_settings_readiness() -> dict[str, Any]:"""Build the current admin-scoped readiness matrix."""+ from deeptutor.modules.catalog import module_enabledfrom deeptutor.multi_user.knowledge_access import current_kb_managerfrom deeptutor.services.config import get_model_catalog_service, get_runtime_settings_service- from deeptutor.services.parsing.engines.factory import get_parser, list_engines- from deeptutor.services.rag.preflight import engine_preflightfrom deeptutor.services.settings.interface_settings import get_enabled_optional_tools- from deeptutor.video_learning import load_video_learning_settings- from deeptutor.visualizers.registry import get_visualizer_registry- manager = current_kb_manager()- kb_names = manager.list_knowledge_bases()+ manager = current_kb_manager() if module_enabled("knowledge") else None+ kb_names = manager.list_knowledge_bases() if manager else []rows: list[dict[str, Any]] = []# An embedding model is dead weight until something needs to be indexed,@@ -905,7 +902,11 @@ async def build_settings_readiness() -> dict[str, Any]:runtime_service = get_runtime_settings_service()parsing = runtime_service.load_document_parsing(include_process_overrides=True)- parser_entries = list_engines()+ parser_entries = []+ if module_enabled("parsing"):+ from deeptutor.services.parsing.engines.factory import get_parser, list_engines++ parser_entries = list_engines()parser_readiness: dict[str, dict[str, Any]] = {}selected_engine = str(parsing.get("engine") or "")selected_remote_reachable: bool | None = None@@ -945,7 +946,7 @@ async def build_settings_readiness() -> dict[str, Any]:))- default_kb = manager.get_default()+ default_kb = manager.get_default() if manager else Noneknowledge_entries: list[dict[str, Any]] = []for name in kb_names:try:@@ -957,6 +958,7 @@ async def build_settings_readiness() -> dict[str, Any]:from deeptutor.services.embedding.config import embedding_config_scopefrom deeptutor.services.rag.embedding_binding import binding_status+ from deeptutor.services.rag.preflight import engine_preflightbinding_state, embedding = binding_status(manager.config.get("knowledge_bases", {}).get(name, {})@@ -988,14 +990,21 @@ async def build_settings_readiness() -> dict[str, Any]:)rows.extend(knowledge_base_rows(knowledge_entries))- visualizers = visualizer_rows(- get_visualizer_registry().public_catalog(),- manim_available=_module_available("manim"),- )+ visualizers = []+ if module_enabled("visualize"):+ from deeptutor.visualizers.registry import get_visualizer_registry++ visualizers = visualizer_rows(+ get_visualizer_registry().public_catalog(),+ manim_available=module_enabled("renderer-manim") and _module_available("manim"),+ )rows.extend(visualizers)dependency_rows = {str(row["id"]): row for row in (*catalog_rows, *visualizers)}rows.extend(tool_rows(get_enabled_optional_tools(), dependency_rows))- rows.extend(video_learning_rows(load_video_learning_settings()))+ if module_enabled("reading"):+ from deeptutor.video_learning import load_video_learning_settings++ rows.extend(video_learning_rows(load_video_learning_settings()))integrations = runtime_service.load_integrations(include_process_overrides=True)system = runtime_service.load_system(include_process_overrides=True)diff --git a/deeptutor/services/config/settings_spec.py b/deeptutor/services/config/settings_spec.pyindex 0cf9ad99b..1ec8e97cc 100644--- a/deeptutor/services/config/settings_spec.py+++ b/deeptutor/services/config/settings_spec.py@@ -263,6 +263,10 @@ def _parsing_engine_choices() -> tuple[SettingChoice, ...]:turns an unavailable choice into an install offer instead of pretending theengine does not exist."""+ from deeptutor.modules.catalog import module_enabled++ if not module_enabled("parsing"):+ return ()from deeptutor.services.parsing.engines._install import installable_enginesfrom deeptutor.services.parsing.engines.factory import list_engines@@ -293,6 +297,10 @@ def _parsing_engine_choices() -> tuple[SettingChoice, ...]:def _validate_parsing_engine(value: str) -> str | None:+ from deeptutor.modules.catalog import module_enabled++ if not module_enabled("parsing"):+ return "Install the parsing module first: deeptutor module install parsing"from deeptutor.services.parsing.engines.factory import is_engine_availableif is_engine_available(value):diff --git a/deeptutor/services/cron/executor.py b/deeptutor/services/cron/executor.pyindex 2bbae9f3e..13396e164 100644--- a/deeptutor/services/cron/executor.py+++ b/deeptutor/services/cron/executor.py@@ -76,6 +76,9 @@ async def _maybe_send_desktop_notification(job: CronJob, text: str) -> None:async def _execute_partner_job(job: CronJob) -> tuple[str, str | None]:"""Run the partner turn and publish the reply through the original channel."""+ from deeptutor.modules.catalog import require_module++ require_module("partners")from deeptutor.partners.bus.events import InboundMessagefrom deeptutor.services.partners import get_partner_managerdiff --git a/deeptutor/services/cron/module_service.py b/deeptutor/services/cron/module_service.pynew file mode 100644index 000000000..7855a1c95--- /dev/null+++ b/deeptutor/services/cron/module_service.py@@ -0,0 +1,13 @@+"""Background services contributed by this installed module."""+++async def start_cron(application_container) -> None:+ from deeptutor.services.cron import get_cron_service++ await get_cron_service().start()+++async def stop_cron(application_container) -> None:+ from deeptutor.services.cron import get_cron_service++ await get_cron_service().stop()diff --git a/deeptutor/services/doctor.py b/deeptutor/services/doctor.pyindex c51c900d0..4dba8a597 100644--- a/deeptutor/services/doctor.py+++ b/deeptutor/services/doctor.py@@ -225,6 +225,16 @@ def _rag_check(config: dict[str, Any],preflight: Callable[[str], dict[str, Any]],) -> DoctorCheck:+ from deeptutor.modules.catalog import module_enabled++ if not module_enabled("knowledge"):+ return DoctorCheck(+ key="rag",+ label="RAG prerequisites",+ status="skip",+ detail="Knowledge module is unavailable.",+ required=False,+ )knowledge_bases = config.get("knowledge_bases", {})if not isinstance(knowledge_bases, dict) or not knowledge_bases:return DoctorCheck(@@ -387,6 +397,16 @@ async def run_diagnostics(from deeptutor.services.path_service import get_path_servicedata_root = get_path_service().get_user_root()+ from deeptutor.modules.catalog import module_enabled++ if not module_enabled("knowledge"):++ def load_rag_config():+ return {}++ def rag_preflight(_name):+ return {}+if load_rag_config is None:from deeptutor.services.config import get_kb_config_servicediff --git a/deeptutor/services/parsing/engines/_install.py b/deeptutor/services/parsing/engines/_install.pyindex 570fb61e6..a38bb61b1 100644--- a/deeptutor/services/parsing/engines/_install.py+++ b/deeptutor/services/parsing/engines/_install.py@@ -36,20 +36,12 @@ logger = logging.getLogger(__name__)# Engine id -> pip requirement specifiers. Mirrors the optional extras in# pyproject.toml. Engines absent here (text_only built-in, mineru external# CLI/API) have no one-click install.+from deeptutor.modules.catalog import manifests+ENGINE_PIP_SPECS: dict[str, list[str]] = {- "pymupdf4llm": ["pymupdf4llm>=1.28.2"],- # ``all`` is upstream's supported way to install every built-in converter- # dependency (PDF, Office, Outlook, audio, and future additions).- "markitdown": ["markitdown[all]>=0.1.7"],- # Keep the base converter and every format-specific dependency aligned- # with the Docling compatibility floor. ``format-video`` also brings the- # ASR dependencies used by audio; legacy Office still needs LibreOffice- # and video conversion still needs ffmpeg on the host, per Docling.- "docling": [- "docling[xbrl]>=2.123.1",- "docling-slim[format-iwork,format-opendocument,format-video]>=2.123.1",- ],- "liteparse": ["liteparse>=2.14.2"],+ row["parser_engine"]: list(row["requirements"])+ for row in manifests().values()+ if "parser_engine" in row}# Engine id -> console-script argv that downloads its model weights. The script@@ -135,16 +127,18 @@ class BackgroundJobManager:self._cancel_requested = Falsedef start_install(self, *, engine: str, specs: list[str]) -> dict[str, Any]:- # Always refresh an installed engine so one-click setup follows the- # newest release and picks up newly supported formats.- cmd = [sys.executable, "-m", "pip", "install", "--upgrade", "--no-input", *specs]- return self._launch(- kind="install",- engine=engine,- cmd=cmd,- env={"PIP_DISABLE_PIP_VERSION_CHECK": "1"},- on_success=_invalidate_import_caches,- )+ # Host-package changes cannot be safe while turns/API workers run.+ # Model downloads remain background jobs because they do not mutate code.+ if engine not in ENGINE_PIP_SPECS or specs != ENGINE_PIP_SPECS[engine]:+ return {"ok": False, "message": "Unknown parser installation request."}+ return {+ "ok": False,+ "message": (+ "Stop DeepTutor, then run `deeptutor module install parser-"+ + engine+ + "` in this environment and restart. User data is preserved."+ ),+ }def start_model_download(self, *, engine: str, cmd: list[str]) -> dict[str, Any]:return self._launch(kind="models", engine=engine, cmd=cmd)diff --git a/deeptutor/services/parsing/engines/factory.py b/deeptutor/services/parsing/engines/factory.pyindex 760ccc7a5..6b8a89b14 100644--- a/deeptutor/services/parsing/engines/factory.py+++ b/deeptutor/services/parsing/engines/factory.py@@ -155,10 +155,39 @@ def get_parser(name: str) -> Parser:loader = _ENGINE_LOADERS.get(_normalize_name(name))if loader is None:raise ParserError(f"Unknown document-parsing engine: {name!r}")- return loader()()+ parser = loader()()+ from deeptutor.modules.catalog import manifests, module_enabled++ owner = next(+ (+ key+ for key, row in manifests().items()+ if row.get("parser_engine") == _normalize_name(name)+ ),+ None,+ )+ if (+ owner+ and not module_enabled(owner)+ and not getattr(parser.resolve_config(), "is_remote", False)+ ):+ raise ParserError(f"Install or enable the parser module: deeptutor module install {owner}")+ return parserdef is_engine_available(name: str) -> bool:+ from deeptutor.modules.catalog import manifests, module_enabled++ owner = next(+ (+ key+ for key, row in manifests().items()+ if row.get("parser_engine") == _normalize_name(name)+ ),+ None,+ )+ if owner and not module_enabled(owner):+ return Falseloader = _ENGINE_LOADERS.get(_normalize_name(name))if loader is None:return Falsediff --git a/deeptutor/services/parsing/engines/mineru/local.py b/deeptutor/services/parsing/engines/mineru/local.pyindex 26cffca8c..a7a09853c 100644--- a/deeptutor/services/parsing/engines/mineru/local.py+++ b/deeptutor/services/parsing/engines/mineru/local.py@@ -223,7 +223,7 @@ def parse_document_with_mineru_result(tail: deque[str] = deque(maxlen=40)last_emit = 0.0- from deeptutor.knowledge.indexing_run import IndexingCancelled, current_run+ from deeptutor.services.parsing.progress import IndexingCancelled, current_runrun = current_run()started = activity = time.monotonic()diff --git a/deeptutor/services/parsing/progress.py b/deeptutor/services/parsing/progress.pynew file mode 100644index 000000000..8bdb7e83e--- /dev/null+++ b/deeptutor/services/parsing/progress.py@@ -0,0 +1,63 @@+"""Optional parsing progress context, independent of knowledge storage."""++from __future__ import annotations++from contextvars import ContextVar+import re+from typing import Any, Protocol+++class ParseProgress(Protocol):+ def phase(self, name: str, **kwargs: Any) -> None: ...+ def document(self, source: Any, status: str, **kwargs: Any) -> None: ...+ def check(self) -> None: ...+++_CURRENT: ContextVar[ParseProgress | None] = ContextVar("indexing_run", default=None)+++class IndexingCancelled(RuntimeError):+ pass+++def current_run() -> ParseProgress | None:+ return _CURRENT.get()+++def _redact(detail: str) -> str:+ text = re.sub(r"(?i)(bearer\s+)[^\s]+", r"\1[redacted]", str(detail))+ text = re.sub(+ r"(?i)((?:api[_-]?key|token|secret|password|signature|authorization)\s*[=:]\s*)[^\s&]+",+ r"\1[redacted]",+ text,+ )+ text = re.sub(+ r'(?i)(["\']?(?:api[_-]?key|token|secret|password|signature|authorization)["\']?\s*[:=]\s*)["\'][^"\']*["\']',+ r'\1"[redacted]"',+ text,+ )+ text = re.sub(r"(https?://)[^/\s@]+:[^/\s@]+@", r"\1[redacted]@", text)+ return text[-1600:]+++def failure_code(exc: BaseException) -> str:+ text = str(exc).casefold()+ if isinstance(exc, (TimeoutError,)) or "timeout" in text or "timed out" in text:+ return "timeout"+ if isinstance(exc, MemoryError) or "out of memory" in text or "resource exhausted" in text:+ return "resource_exhaustion"+ if (+ isinstance(exc, (FileNotFoundError, ModuleNotFoundError))+ or "not installed" in text+ or "cli_missing" in text+ ):+ return "dependency_missing"+ if "unsupported" in text or "doesn't support" in text:+ return "unsupported_input"+ if "download" in text:+ return "model_download_failed"+ if "embedding" in text or "vector" in text:+ return "embedding_failed"+ if "no content" in text or "no output" in text or "invalid" in text:+ return "invalid_output"+ return "runtime_failure"diff --git a/deeptutor/services/parsing/service.py b/deeptutor/services/parsing/service.pyindex 5834ea086..9ae410322 100644--- a/deeptutor/services/parsing/service.py+++ b/deeptutor/services/parsing/service.py@@ -102,7 +102,7 @@ class ParseService:return not supported or _matches_supported_format(source_path, supported)def parse(self, source_path: str | Path, *, engine=None, on_output=None) -> ParsedDocument:- from deeptutor.knowledge.indexing_run import _redact, current_run, failure_code+ from deeptutor.services.parsing.progress import _redact, current_run, failure_coderun = current_run()source = Path(source_path)@@ -189,7 +189,7 @@ class ParseService:markdown, blocks, asset_dir = "", None, Noneif markdown.strip() or blocks:logger.info("Parse cache hit for %s (%s/%s)", source_path.name, engine_name, sig)- from deeptutor.knowledge.indexing_run import current_run+ from deeptutor.services.parsing.progress import current_runif run := current_run():run.document(source_path, "parsed", parse_reused=True)diff --git a/deeptutor/services/partners/module_service.py b/deeptutor/services/partners/module_service.pynew file mode 100644index 000000000..a32622a3f--- /dev/null+++ b/deeptutor/services/partners/module_service.py@@ -0,0 +1,15 @@+"""Background services contributed by this installed module."""+++async def start_partners(application_container) -> None:+ from deeptutor.services.partners import get_partner_manager++ manager = get_partner_manager()+ manager.configure_runtime_owner(application_container.worker_id)+ await manager.autostart_partners(application_container)+++async def stop_partners(application_container) -> None:+ from deeptutor.services.partners import get_partner_manager++ await get_partner_manager().stop_all(preserve_auto_start=True)diff --git a/deeptutor/services/partners/scope.py b/deeptutor/services/partners/scope.pyindex 7bee1b941..4f8a134f1 100644--- a/deeptutor/services/partners/scope.py+++ b/deeptutor/services/partners/scope.py@@ -10,20 +10,10 @@ scope is installed via ``user_context(...)``.from __future__ import annotations+from deeptutor.core.identities import PARTNER_USER_PREFIX, is_partner_user_id, partner_user_idfrom deeptutor.multi_user.models import CurrentUser, UserScopefrom deeptutor.partners.config.paths import get_partner_workspace-PARTNER_USER_PREFIX = "partner_"---def partner_user_id(partner_id: str) -> str:- return f"{PARTNER_USER_PREFIX}{partner_id}"---def is_partner_user_id(user_id: str) -> bool:- """Whether *user_id* names a synthetic partner scope rather than a person."""- return user_id.startswith(PARTNER_USER_PREFIX)-def partner_scope(partner_id: str) -> UserScope:workspace = get_partner_workspace(partner_id)diff --git a/deeptutor/services/partners/workspace.py b/deeptutor/services/partners/workspace.pyindex 7c4d23799..fb9915b03 100644--- a/deeptutor/services/partners/workspace.py+++ b/deeptutor/services/partners/workspace.py@@ -178,6 +178,9 @@ def _err(exc: Exception) -> str:def _copy_knowledge_base(kb_ref: str, partner_root: Path) -> str:+ from deeptutor.modules.catalog import require_module++ require_module("knowledge")from deeptutor.knowledge.kb_types import NON_RETRIEVABLE_KB_TYPES, is_connected_kbfrom deeptutor.knowledge.manager import KnowledgeBaseManagerfrom deeptutor.multi_user.knowledge_access import resolve_kbdiff --git a/deeptutor/services/rag/file_routing.py b/deeptutor/services/rag/file_routing.pyindex 24c57a981..cd2ef2c5c 100644--- a/deeptutor/services/rag/file_routing.py+++ b/deeptutor/services/rag/file_routing.py@@ -1,401 +1,5 @@-"""-File Type Router-================+"""Compatibility import for shared document classification."""-Centralized file type classification and routing for the RAG pipeline.-Determines the appropriate processing method for each document type.-"""+from deeptutor.utils.file_types import DocumentType, FileClassification, FileTypeRouter-from dataclasses import dataclass-from enum import Enum-import logging-from pathlib import Path-from typing import List--logger = logging.getLogger(__name__)---class DocumentType(Enum):- """Document type classification."""-- PDF = "pdf"- TEXT = "text"- MARKDOWN = "markdown"- DOCX = "docx"- SPREADSHEET = "spreadsheet"- PRESENTATION = "presentation"- EPUB = "epub"- IMAGE = "image"- DOCUMENT = "document"- UNKNOWN = "unknown"---@dataclass-class FileClassification:- """Result of file classification."""-- parser_files: List[str]- text_files: List[str]- image_files: List[str]- unsupported: List[str]---class FileTypeRouter:- """File type router for the RAG pipeline.-- Classifies files before processing to route them to appropriate handlers:- - PDF / Office / EPUB files -> parser-based text extraction- - Text files -> Direct read (fast, simple)- - Unsupported -> Skip with warning- """-- PDF_EXTENSIONS = {".pdf"}- OFFICE_EXTENSIONS = {".docx", ".xlsx", ".pptx"}- EPUB_EXTENSIONS = {".epub"}- PARSER_EXTENSIONS = PDF_EXTENSIONS | OFFICE_EXTENSIONS | EPUB_EXTENSIONS-- TEXT_EXTENSIONS = {- # Plain text & docs- ".txt",- ".text",- ".log",- ".md",- ".markdown",- ".rst",- ".asciidoc",- # Data / config- ".json",- ".jsonc",- ".json5",- ".yaml",- ".yml",- ".toml",- ".csv",- ".tsv",- ".ini",- ".cfg",- ".conf",- ".env",- ".properties",- # Typesetting- ".tex",- ".latex",- ".bib",- # JavaScript / TypeScript family- ".js",- ".mjs",- ".cjs",- ".ts",- ".mts",- ".cts",- ".jsx",- ".tsx",- # Web frameworks- ".vue",- ".svelte",- # Python- ".py",- # JVM languages- ".java",- ".kt",- ".kts",- ".scala",- ".groovy",- ".gradle",- # Systems languages- ".c",- ".h",- ".cpp",- ".cc",- ".cxx",- ".hpp",- ".hh",- ".hxx",- ".cs",- ".go",- ".rs",- ".zig",- ".nim",- # Apple platforms- ".swift",- ".m",- ".mm",- # Scripting- ".rb",- ".php",- ".pl",- ".pm",- ".lua",- ".r",- ".jl",- ".dart",- # Functional- ".hs",- ".clj",- ".cljs",- ".cljc",- ".ex",- ".exs",- ".erl",- ".ml",- ".mli",- ".fs",- ".fsx",- ".lisp",- ".lsp",- ".scm",- ".rkt",- # Web markup / styles- ".html",- ".htm",- ".xml",- ".svg",- ".css",- ".scss",- ".sass",- ".less",- # Smart contracts- ".sol",- # Shells / editors- ".sh",- ".bash",- ".zsh",- ".fish",- ".ps1",- ".vim",- # Query / IDL- ".sql",- ".graphql",- ".gql",- ".proto",- # Build / infra- ".cmake",- ".mk",- ".tf",- ".hcl",- ".nginxconf",- ".dockerfile",- }-- IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".tif"}-- @classmethod- def get_document_type(cls, file_path: str) -> DocumentType:- """Classify a single file by its type."""- ext = cls.get_extension(file_path)-- if ext in cls.PDF_EXTENSIONS:- return DocumentType.PDF- elif ext in cls.TEXT_EXTENSIONS:- return DocumentType.TEXT- elif ext == ".docx":- return DocumentType.DOCX- elif ext == ".xlsx":- return DocumentType.SPREADSHEET- elif ext == ".pptx":- return DocumentType.PRESENTATION- elif ext in cls.EPUB_EXTENSIONS:- return DocumentType.EPUB- elif ext in cls.IMAGE_EXTENSIONS:- return DocumentType.IMAGE- elif ext in cls.get_parser_extensions():- # Formats added by optional rich parsers, such as OpenDocument,- # legacy Office, mail, archives, audio/video and scientific data.- return DocumentType.DOCUMENT- else:- if cls._is_text_file(file_path):- return DocumentType.TEXT- if cls.active_parser_accepts_any_format():- return DocumentType.DOCUMENT- return DocumentType.UNKNOWN-- @classmethod- def _is_text_file(cls, file_path: str, sample_size: int = 8192) -> bool:- """Detect if a file is text-based by examining its content."""- try:- with open(file_path, "rb") as f:- chunk = f.read(sample_size)-- if b"\x00" in chunk:- return False-- chunk.decode("utf-8")- return True- except (UnicodeDecodeError, IOError, OSError):- return False-- @classmethod- def classify_files(cls, file_paths: List[str]) -> FileClassification:- """Classify a list of files by processing method."""- parser_files = []- text_files = []- image_files = []- unsupported = []-- for path in file_paths:- doc_type = cls.get_document_type(path)-- if doc_type in (- DocumentType.PDF,- DocumentType.DOCX,- DocumentType.SPREADSHEET,- DocumentType.PRESENTATION,- DocumentType.EPUB,- DocumentType.DOCUMENT,- ):- parser_files.append(path)- elif doc_type in (DocumentType.TEXT, DocumentType.MARKDOWN):- text_files.append(path)- elif doc_type == DocumentType.IMAGE:- image_files.append(path)- else:- unsupported.append(path)-- logger.debug(- f"Classified {len(file_paths)} files: "- f"{len(parser_files)} parser, {len(text_files)} text, "- f"{len(image_files)} image, {len(unsupported)} unsupported"- )-- return FileClassification(- parser_files=parser_files,- text_files=text_files,- image_files=image_files,- unsupported=unsupported,- )-- TEXT_DECODING_CANDIDATES = (- "utf-8",- "utf-8-sig",- "gbk",- "gb2312",- "gb18030",- "latin-1",- "cp1252",- )-- @classmethod- def decode_bytes(cls, data: bytes) -> str:- """Decode raw bytes using the same fallback chain as read_text_file.-- Used by the chat-attachment extractor so path-based and bytes-based- callers share one source of truth for supported encodings.- """- for encoding in cls.TEXT_DECODING_CANDIDATES:- try:- return data.decode(encoding)- except UnicodeDecodeError:- continue- return data.decode("utf-8", errors="replace")-- @classmethod- async def read_text_file(cls, file_path: str) -> str:- """Read a text file with automatic encoding detection."""- for encoding in cls.TEXT_DECODING_CANDIDATES:- try:- with open(file_path, "r", encoding=encoding) as f:- text = f.read()- break- except UnicodeDecodeError:- continue-- else:- with open(file_path, "rb") as f:- text = f.read().decode("utf-8", errors="replace")-- if Path(file_path).suffix.lower() == ".bib":- from deeptutor.utils.bibtex_converter import bibtex_to_markdown-- return bibtex_to_markdown(text, Path(file_path).stem)- return text-- @classmethod- def needs_parser(cls, file_path: str) -> bool:- """Quick check if a single file needs parser processing."""- doc_type = cls.get_document_type(file_path)- return doc_type in (- DocumentType.PDF,- DocumentType.DOCX,- DocumentType.SPREADSHEET,- DocumentType.PRESENTATION,- DocumentType.EPUB,- DocumentType.IMAGE,- DocumentType.DOCUMENT,- )-- @classmethod- def is_text_readable(cls, file_path: str) -> bool:- """Check if a file can be read directly as text."""- doc_type = cls.get_document_type(file_path)- return doc_type in (DocumentType.TEXT, DocumentType.MARKDOWN)-- @classmethod- def get_supported_extensions(cls) -> set[str]:- """Get the set of all supported file extensions."""- return cls.get_parser_extensions() | cls.TEXT_EXTENSIONS | cls.IMAGE_EXTENSIONS-- @classmethod- def get_parser_extensions(cls) -> set[str]:- """Parser-backed formats accepted by the knowledge-base pipeline.-- The built-in set remains separate because ``document_extractor`` uses- it for text-only parsing. Lightweight format helpers contribute every- adapter's current upstream list without importing optional engines.- """- from deeptutor.services.parsing.engines.formats import known_parser_formats-- return cls.PARSER_EXTENSIONS | set(known_parser_formats())-- @classmethod- def active_parser_accepts_any_format(cls) -> bool:- """Whether the selected engine delegates format detection at runtime."""- try:- from deeptutor.services.parsing.engines.factory import get_parser- from deeptutor.services.parsing.service import get_parse_service-- service = get_parse_service()- return not get_parser(service.active_engine()).supported_formats()- except Exception:- return False-- @classmethod- def get_extension(- cls, file_path: str | Path, extensions: set[str] | frozenset[str] | None = None- ) -> str:- """Return the longest recognized suffix, including compound suffixes."""- name = Path(file_path).name.lower()- candidates = extensions if extensions is not None else cls.get_supported_extensions()- matches = [- extension.lower() for extension in candidates if name.endswith(extension.lower())- ]- return max(matches, key=len) if matches else Path(file_path).suffix.lower()-- @classmethod- def has_supported_extension(cls, file_path: str | Path) -> bool:- """Return True when ``file_path`` has a supported extension.-- The check is case-insensitive so files such as ``Report.PDF`` are- discovered consistently across upload, CLI, folder sync, and reindex.- """- if cls.active_parser_accepts_any_format():- return True- supported = cls.get_supported_extensions()- return cls.get_extension(file_path, supported) in supported-- @classmethod- def collect_supported_files(cls, directory: str | Path, recursive: bool = False) -> list[Path]:- """Collect supported files from a directory with case-insensitive suffix matching."""- root = Path(directory)- if not root.exists() or not root.is_dir():- return []-- paths = root.rglob("*") if recursive else root.iterdir()- return sorted(- (path for path in paths if path.is_file() and cls.has_supported_extension(path)),- key=lambda path: str(path).lower(),- )-- @classmethod- def get_glob_patterns(cls) -> list[str]:- """Get glob patterns for file searching."""- return [f"*{ext}" for ext in sorted(cls.get_supported_extensions())]+__all__ = ["DocumentType", "FileClassification", "FileTypeRouter"]diff --git a/deeptutor/services/rag/pipelines/graphrag/ingestion.py b/deeptutor/services/rag/pipelines/graphrag/ingestion.pyindex b994b559a..340ec09d8 100644--- a/deeptutor/services/rag/pipelines/graphrag/ingestion.py+++ b/deeptutor/services/rag/pipelines/graphrag/ingestion.py@@ -17,7 +17,7 @@ import loggingfrom pathlib import Pathfrom typing import Iterable-from deeptutor.services.rag.file_routing import FileTypeRouter+from deeptutor.utils.file_types import FileTypeRouterfrom . import storagediff --git a/deeptutor/services/rag/pipelines/llamaindex/document_loader.py b/deeptutor/services/rag/pipelines/llamaindex/document_loader.pyindex 78608014a..64763b5e9 100644--- a/deeptutor/services/rag/pipelines/llamaindex/document_loader.py+++ b/deeptutor/services/rag/pipelines/llamaindex/document_loader.py@@ -27,10 +27,10 @@ from deeptutor.services.embedding import get_embedding_clientfrom deeptutor.services.llm.image_caption_batch import ImageCaptionBatcherfrom deeptutor.services.llm.image_caption_cache import complete_image_captionfrom deeptutor.services.llm.image_description import get_image_description_client-from deeptutor.services.rag.file_routing import FileTypeRouterfrom deeptutor.services.rag.source_pages import SourcePageErrorfrom deeptutor.services.rag.visual_assets import VisualAssetCandidate, collect_visual_assetsfrom deeptutor.utils.document_validator import DocumentValidator+from deeptutor.utils.file_types import FileTypeRouterfrom .config import image_description_batch_size, image_description_limitsdiff --git a/deeptutor/services/session/_turn_runtime_shared.py b/deeptutor/services/session/_turn_runtime_shared.pyindex 379b9f61e..ad171ab66 100644--- a/deeptutor/services/session/_turn_runtime_shared.py+++ b/deeptutor/services/session/_turn_runtime_shared.py@@ -730,6 +730,11 @@ def _timed_media_viewport(value: Any) -> dict[str, float]: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_referencesreturn normalize_reading_references(value)diff --git a/deeptutor/services/session/attachment_parsing.py b/deeptutor/services/session/attachment_parsing.pyindex 201838938..00d7c98c4 100644--- a/deeptutor/services/session/attachment_parsing.py+++ b/deeptutor/services/session/attachment_parsing.py@@ -9,7 +9,6 @@ import refrom typing import Anyfrom deeptutor.services.config.runtime_settings import get_chat_attachment_limits-from deeptutor.services.parsing import get_parse_servicefrom deeptutor.services.storage import AttachmentStorefrom deeptutor.utils.document_images import find_markers@@ -30,6 +29,11 @@ async def parse_chat_pdf_attachments(contexts = list(document_texts)if not any(str(record.get("filename") or "").lower().endswith(".pdf") for record in updated):return updated, contexts+ from deeptutor.modules.catalog import require_module++ require_module("parsing")+ from deeptutor.services.parsing import get_parse_service+limits = get_chat_attachment_limits()total_chars = sum(int(record.get("extracted_chars") or 0)diff --git a/deeptutor/services/session/source_inventory.py b/deeptutor/services/session/source_inventory.pyindex 01bd1d7f9..bac015fac 100644--- a/deeptutor/services/session/source_inventory.py+++ b/deeptutor/services/session/source_inventory.py@@ -34,7 +34,6 @@ import hashlibimport loggingfrom typing import Any, Sequence-from deeptutor.reading.references import resolve_reading_sourcesfrom deeptutor.services.session.protocol import SessionStoreProtocollogger = logging.getLogger(__name__)@@ -779,6 +778,14 @@ def _add_reading_sources(turns instead of leaving a stale or spoofable copy in session metadata."""+ if not references:+ return+ from deeptutor.modules.catalog import module_enabled++ if not module_enabled("reading"):+ return+ from deeptutor.reading.references import resolve_reading_sources+for source in resolve_reading_sources(list(references)):if source.source_id in inv and not fresh:continue@@ -821,6 +828,10 @@ def _resolve_book_section(book_reference: dict[str, Any]) -> tuple[str, str]:reference is rendered independently (so the per-book ``bk-{book_id}``source id stays stable). Returns ``("", "")`` on failure."""+ from deeptutor.modules.catalog import module_enabled++ if not module_enabled("books"):+ return "", ""from deeptutor.book.context import build_book_contexttry:diff --git a/deeptutor/services/session/turns/executor.py b/deeptutor/services/session/turns/executor.pyindex 69635f9b1..ea538e76d 100644--- a/deeptutor/services/session/turns/executor.py+++ b/deeptutor/services/session/turns/executor.py@@ -241,17 +241,16 @@ class TurnExecutor:assert_learning_material(material_id)from deeptutor.agents.notebook import NotebookAnalysisAgent- from deeptutor.book.context import build_book_contextfrom deeptutor.core.context import Attachment, TurnRuntimeContext, UnifiedContext+ from deeptutor.core.source_context import SourceContext+ from deeptutor.modules.catalog import require_modulefrom deeptutor.services.learning_journal import get_learning_journal_store- from deeptutor.services.memory import get_memory_storefrom deeptutor.services.model_selection.runtime import (activate_llm_selection,)from deeptutor.services.model_selection.runtime import (reset_llm_selection as reset_active_llm_selection,)- from deeptutor.services.notebook import get_notebook_managerfrom deeptutor.services.workspace import get_content_workspace_servicerequest_config = dict(payload.get("config", {}) or {})@@ -294,7 +293,16 @@ class TurnExecutor:payload.get("partner_group_references"))question_notebook_references = payload.get("question_notebook_references", []) or []- book_context_result = build_book_context(payload.get("book_references", []) or [])+ book_context_result = SourceContext()+ if payload.get("book_references"):+ require_module("books")+ from deeptutor.book.context import build_book_context++ book_context_result = build_book_context(payload["book_references"])+ if notebook_references:+ require_module("notebook")+ from deeptutor.services.notebook import get_notebook_manager+book_references = book_context_result.referencesreading_references = _reading_references(payload.get("reading_references"))memory_references = _extract_memory_references(payload)@@ -574,8 +582,12 @@ class TurnExecutor:on_event=_emit_context_event,leaf_message_id=branch_parent_id,)- memory_store = get_memory_store()- memory_context = memory_store.read_l3_concat() if memory_references else ""+ memory_context = ""+ if memory_references:+ require_module("memory")+ from deeptutor.services.memory import get_memory_store++ memory_context = get_memory_store().read_l3_concat()# One snapshot per turn; selected-text tutoring stays independent# of an unrelated mission from earlier conversations (#1407).@@ -865,6 +877,9 @@ class TurnExecutor:# Audio overview reads the page itself and takes the message as# its topic, so the page must not be folded into the message.elif payload.get("note_document_id") and capability_name != "audio_overview":+ from deeptutor.modules.catalog import require_module++ require_module("co-writer")from deeptutor.capabilities.notes.capability import note_action_contextworkspace_context = await asyncio.to_thread(@@ -1228,6 +1243,9 @@ class TurnExecutor:and note_generation.get("block_id")and payload.get("note_document_id")):+ from deeptutor.modules.catalog import require_module++ require_module("co-writer")from deeptutor.capabilities.notes.generation import propose_generated_blockzh = str(payload.get("language", "en") or "en").startswith("zh")diff --git a/deeptutor/services/session/turns/request_preparer.py b/deeptutor/services/session/turns/request_preparer.pyindex 71bef7a9d..2d1a4fa8e 100644--- a/deeptutor/services/session/turns/request_preparer.py+++ b/deeptutor/services/session/turns/request_preparer.py@@ -205,8 +205,8 @@ class TurnRequestPreparer:# Freeze the content binding at admission, before scheduling the turn.# Existing conversations are moved through the organization endpoint;# a stale tab must never move one by sending its cached preference.+ from deeptutor.core.identities import is_partner_user_idfrom deeptutor.multi_user.context import get_current_user- from deeptutor.services.partners.scope import is_partner_user_idfrom deeptutor.services.workspace import get_content_workspace_servicefrom deeptutor.services.workspace.context import get_workspace_scope@@ -436,7 +436,6 @@ class TurnRequestPreparer:# the tutor may change it mid-turn with ``mastery_mode`` and the# learner may change it from the header, so the value a turn starts# with is only where it starts.- from deeptutor.capabilities.mastery.mode import enforced_mode# ``or``, not "is the key present": the client writes this key on every# turn and leaves it null whenever it does not happen to hold the mode@@ -452,7 +451,14 @@ class TurnRequestPreparer:# ``enforced_mode`` rather than ``normalize_mode``: a conversation that# never recorded a mode must stay unrecorded all the way down to the# tools, which read the absence as "enforce nothing".- mastery_session_mode = enforced_mode(raw_mastery_mode)+ mastery_session_mode = None+ if raw_mastery_mode:+ from deeptutor.modules.catalog import require_module++ require_module("mastery")+ from deeptutor.capabilities.mastery.mode import enforced_mode++ mastery_session_mode = enforced_mode(raw_mastery_mode)payload = {**payload,"mastery_path_id": mastery_path_id,diff --git a/deeptutor/services/skill/service.py b/deeptutor/services/skill/service.pyindex 18461e2f0..b46517291 100644--- a/deeptutor/services/skill/service.py+++ b/deeptutor/services/skill/service.py@@ -1045,8 +1045,8 @@ def get_admin_skill_service() -> SkillService:def get_skill_service() -> SkillService:+ from deeptutor.core.identities import is_partner_user_idfrom deeptutor.multi_user.context import get_current_user- from deeptutor.services.partners.scope import is_partner_user_idfrom deeptutor.services.workspace import get_content_workspace_serviceroot = (diff --git a/deeptutor/services/storage/attachment_store.py b/deeptutor/services/storage/attachment_store.pyindex 1add9469b..696b5e90c 100644--- a/deeptutor/services/storage/attachment_store.py+++ b/deeptutor/services/storage/attachment_store.py@@ -36,9 +36,9 @@ import shutilfrom typing import Protocol, runtime_checkablefrom urllib.parse import quote-from deeptutor.partners.helpers import safe_filenamefrom deeptutor.services.config import load_system_settingsfrom deeptutor.services.path_service import get_path_service+from deeptutor.utils.filenames import safe_filenamelogger = logging.getLogger(__name__)diff --git a/deeptutor/services/suggestions.py b/deeptutor/services/suggestions.pyindex af709a3f2..85f6a7e2a 100644--- a/deeptutor/services/suggestions.py+++ b/deeptutor/services/suggestions.py@@ -331,6 +331,10 @@ def _render_l3(cap: int) -> str:"Unsure"), and reading them is exactly the model's job; a lookup table herewould be a second place for that vocabulary to drift."""+ from deeptutor.modules.catalog import module_enabled++ if not module_enabled("memory"):+ return ""from deeptutor.services.memory import get_memory_storetry:@@ -382,6 +386,10 @@ def _collect_material(trace_count: int) -> _Material:what they are in the middle of, and which surface it happened on saysnothing about that."""+ from deeptutor.modules.catalog import module_enabled++ if not module_enabled("memory"):+ return _Material(profile="", topics=[])from deeptutor.services.memory import recallseen: set[str] = set()diff --git a/deeptutor/services/web_source/sync.py b/deeptutor/services/web_source/sync.pyindex fcf63aa62..c422ee723 100644--- a/deeptutor/services/web_source/sync.py+++ b/deeptutor/services/web_source/sync.py@@ -80,8 +80,8 @@ async def _rebuild_index_after_removal(base_dir: str,) -> int:"""Rebuild the bound provider so removed pages cannot remain retrievable."""- from deeptutor.services.rag.file_routing import FileTypeRouterfrom deeptutor.services.rag.service import RAGService+ from deeptutor.utils.file_types import FileTypeRouterfiles = FileTypeRouter.collect_supported_files(raw_dir, recursive=True)if not files:diff --git a/deeptutor/services/workspace/knowledge.py b/deeptutor/services/workspace/knowledge.pyindex 5c9c84d6b..b623c8fe5 100644--- a/deeptutor/services/workspace/knowledge.py+++ b/deeptutor/services/workspace/knowledge.py@@ -8,7 +8,7 @@ from dataclasses import replaceimport jsonfrom pathlib import Path-from fastapi import HTTPException+from deeptutor.core.errors import AccessErrorlibrary_request: ContextVar[bool] = ContextVar("knowledge_library_request", default=False)# The workspace whose library page made a library request. Library requests@@ -47,7 +47,7 @@ def parse_kb_id(value: str) -> tuple[str, str] | None:prefix, separator, name = value.partition(":kb:")if separator and prefix[len("workspace:") :]:return prefix[len("workspace:") :], name- raise HTTPException(status_code=404, detail="Invalid knowledge resource reference")+ raise AccessError(status_code=404, detail="Invalid knowledge resource reference")return None@@ -103,7 +103,7 @@ def resolve_qualified(kb_ref: str, *, require_write=False):finally:library_request.reset(token)except WorkspaceError as exc:- raise HTTPException(+ raise AccessError(status_code=404, detail="Knowledge resource workspace is unavailable") from excreturn replace(resource, id=kb_ref)@@ -173,7 +173,7 @@ def resolve_selected(kb_ref: str, selected: list[str], *, require_write=False):matches = selected[:1]if len(matches) == 1 and parse_kb_id(kb_ref) is None and not kb_ref.startswith("admin:kb:"):return resolve_qualified(matches[0], require_write=require_write)- raise HTTPException(status_code=403, detail="Knowledge base is not assigned to this workspace")+ raise AccessError(status_code=403, detail="Knowledge base is not assigned to this workspace")# Explicit learning-source choices add read access within the current account;diff --git a/deeptutor/tools/builtin_specs.py b/deeptutor/tools/builtin_specs.pyindex 3fa059e91..2e9e6d6bd 100644--- a/deeptutor/tools/builtin_specs.py+++ b/deeptutor/tools/builtin_specs.py@@ -39,182 +39,14 @@ class BuiltinToolSpec:return tool-def _specs(module: str, members: tuple[tuple[str, str], ...]) -> tuple[BuiltinToolSpec, ...]:- return tuple(BuiltinToolSpec(name, f"{module}:{class_name}") for name, class_name in members)---BUILTIN_TOOL_SPECS: tuple[BuiltinToolSpec, ...] = (- BuiltinToolSpec("write_note", "deeptutor.capabilities.notes.tools:WriteNoteTool"),- BuiltinToolSpec("search_notes", "deeptutor.capabilities.notes.tools:SearchNotesTool"),- BuiltinToolSpec("note_read", "deeptutor.capabilities.notes.tools:NoteReadTool"),- BuiltinToolSpec("note_suggest", "deeptutor.capabilities.notes.tools:NoteSuggestTool"),- *_specs(- "deeptutor.tools.builtin",- (- ("brainstorm", "BrainstormTool"),- ("rag", "RAGTool"),- ("kb_files", "KbFilesTool"),- ("knowledge_frontier", "KnowledgeFrontierTool"),- ("web_search", "WebSearchTool"),- ("reason", "ReasonTool"),- ("paper_search", "PaperSearchToolWrapper"),- ("zotero_search", "ZoteroSearchToolWrapper"),- ("read_source", "ReadSourceTool"),- ("read_memory", "ReadMemoryTool"),- ("write_memory", "WriteMemoryTool"),- ("read_skill", "ReadSkillTool"),- ("load_tools", "LoadToolsTool"),- ("web_fetch", "WebFetchTool"),- ("list_notebook", "ListNotebookTool"),- ("list_favorites", "ListFavoritesTool"),- ("save_favorite", "SaveFavoriteTool"),- ("question_bank", "QuestionBankTool"),- ("github", "GithubTool"),- ("ask_user", "AskUserTool"),- ("cron", "CronTool"),- ("geogebra_analysis", "GeoGebraAnalysisTool"),- ),- ),- *_specs(- "deeptutor.tools.learning_journal_tools",- (- ("learning_status", "LearningStatusTool"),- ("learning_update", "LearningUpdateTool"),- ),- ),- *_specs(- "deeptutor.tools.research_tools",- (- ("preprint", "PreprintTool"),- ("research_audit", "ResearchAuditTool"),- ("research_lit", "ResearchLiteratureTool"),- ),- ),- BuiltinToolSpec("exec", "deeptutor.tools.exec_tool:ExecTool"),- *_specs(- "deeptutor.tools.workspace",- (- ("workspace_list", "WorkspaceListTool"),- ("workspace_read", "WorkspaceReadTool"),- ("workspace_search", "WorkspaceSearchTool"),- ("workspace_present", "WorkspacePresentTool"),- ("workspace_export", "WorkspaceExportTool"),- ),- ),- BuiltinToolSpec("submit_visualization", "deeptutor.visualizers.tool:SubmitVisualizationTool"),- BuiltinToolSpec("imagegen", "deeptutor.tools.media_gen_tool:ImagegenTool"),- BuiltinToolSpec("videogen", "deeptutor.tools.media_gen_tool:VideogenTool"),- *_specs(- "deeptutor.tools.mastery_nav",- (- ("mastery_topics", "MasteryTopicsTool"),- ("mastery_sessions", "MasterySessionsTool"),- ("mastery_open_session", "MasteryOpenSessionTool"),- ("mastery_new_session", "MasteryNewSessionTool"),- ),- ),- *_specs(- "deeptutor.capabilities.mastery.tools",- (- ("mastery_status", "MasteryStatusTool"),- ("mastery_prepare_lesson", "MasteryPrepareLessonTool"),- ("mastery_quiz", "MasteryQuizTool"),- ("mastery_note_explained", "MasteryNoteExplainedTool"),- ("mastery_grade", "MasteryGradeTool"),- ("mastery_skip_question", "MasterySkipQuestionTool"),- ("mastery_repair_question", "MasteryRepairQuestionTool"),- ("mastery_defer_objective", "MasteryDeferObjectiveTool"),- ("mastery_assess", "MasteryAssessTool"),- ("mastery_build", "MasteryBuildTool"),- ("mastery_mode", "MasteryModeTool"),- ("mastery_profile", "MasteryProfileTool"),- ("mastery_revise", "MasteryReviseTool"),- ("mastery_paths", "MasteryPathsTool"),- ("mastery_switch", "MasterySwitchTool"),- ("mastery_leave", "MasteryLeaveTool"),- ),- ),- *_specs(- "deeptutor.capabilities.solve.tools",- (- ("solve_plan", "SolvePlanTool"),- ("solve_finish_step", "SolveFinishStepTool"),- ("solve_replan", "SolveReplanTool"),- ),- ),- *_specs(- "deeptutor.capabilities.obsidian.tools",- (- ("obsidian_search", "ObsidianSearchTool"),- ("obsidian_read", "ObsidianReadTool"),- ("obsidian_list", "ObsidianListTool"),- ("obsidian_backlinks", "ObsidianBacklinksTool"),- ("obsidian_links", "ObsidianLinksTool"),- ("obsidian_tags", "ObsidianTagsTool"),- ("obsidian_create_note", "ObsidianCreateNoteTool"),- ("obsidian_append", "ObsidianAppendTool"),- ("obsidian_set_property", "ObsidianSetPropertyTool"),- ),- ),- *_specs(- "deeptutor.capabilities.marginnote4.tools",- (- ("marginnote_search", "MarginNoteSearchTool"),- ("marginnote_read", "MarginNoteReadTool"),- ("marginnote_list", "MarginNoteListTool"),- ("marginnote_documents", "MarginNoteDocumentsTool"),- ("marginnote_links", "MarginNoteLinksTool"),- ("marginnote_tags", "MarginNoteTagsTool"),- ("marginnote_cards", "MarginNoteCardsTool"),- ),- ),- BuiltinToolSpec(- "consult_subagent", "deeptutor.capabilities.subagent.tools:ConsultSubagentTool"- ),- *_specs(- "deeptutor.capabilities.ima.tools",- (- ("ima_list", "ImaListTool"),- ("ima_read", "ImaReadTool"),- ("ima_note_search", "ImaNoteSearchTool"),- ("ima_add_url", "ImaAddUrlTool"),- ("ima_write_note", "ImaWriteNoteTool"),- ),- ),- *_specs(- "deeptutor.capabilities.reading.tools",- (- ("reading_list_tabs", "ReadingListTabsTool"),- ("reading_switch_tab", "ReadingSwitchTabTool"),- ("material_outline", "MaterialOutlineTool"),- ("search_material", "SearchMaterialTool"),- ("read_material", "ReadMaterialTool"),- ("view_figure", "ViewFigureTool"),- ("reader_goto", "ReaderGotoTool"),- ("reader_annotate", "ReaderAnnotateTool"),- ),- ),- *_specs(- "deeptutor.capabilities.setup.tools",- (- ("inspect_setup", "InspectSetupTool"),- ("apply_setting", "ApplySettingTool"),- ("request_credential", "RequestCredentialTool"),- ("run_setup_job", "RunSetupJobTool"),- ),- ),- BuiltinToolSpec(- "propose_partner", "deeptutor.capabilities.partner_authoring.tools:ProposePartnerTool"- ),- BuiltinToolSpec("invoke_other", "deeptutor.capabilities.partner_group.tools:InvokeOtherTool"),- *_specs(- "deeptutor.tools.partner_memory",- (- ("partner_read", "PartnerReadTool"),- ("partner_memorize", "PartnerMemorizeTool"),- ("partner_search", "PartnerSearchTool"),- ),- ),+from deeptutor.modules.catalog import manifests++BUILTIN_TOOL_SPECS: tuple[BuiltinToolSpec, ...] = tuple(+ BuiltinToolSpec(name, spec["class_path"])+ for name, spec in sorted(+ ((name, spec) for module in manifests().values() for name, spec in module["tools"].items()),+ key=lambda row: row[1]["order"],+ ))BUILTIN_TOOL_NAMES: tuple[str, ...] = tuple(spec.name for spec in BUILTIN_TOOL_SPECS)diff --git a/deeptutor/tools/partner_memory.py b/deeptutor/tools/partner_memory.pyindex 91f692f7c..edf4cd451 100644--- a/deeptutor/tools/partner_memory.py+++ b/deeptutor/tools/partner_memory.py@@ -55,8 +55,8 @@ def _concat_l3() -> str:def _resolve_partner_id() -> str | None:"""The active partner id, or ``None`` when not inside a partner scope."""+ from deeptutor.core.identities import PARTNER_USER_PREFIXfrom deeptutor.multi_user.context import get_current_user_or_none- from deeptutor.services.partners.scope import PARTNER_USER_PREFIXuser = get_current_user_or_none()user_id = user.scope.user_id if user and user.scope else ""diff --git a/deeptutor/tools/research_tools.py b/deeptutor/tools/research_tools.pyindex 98118d26b..9e38d5798 100644--- a/deeptutor/tools/research_tools.py+++ b/deeptutor/tools/research_tools.py@@ -36,12 +36,17 @@ def scientific_context(message: str, capability: str = "", enabled_tools=()) ->def _client() -> ResearchClient:+ import os+from deeptutor.multi_user.context import get_current_user_or_none- from deeptutor.services.github_source.client import _tokenuser = get_current_user_or_none()# A deployment token is never borrowed by another account's research turn.- token = _token() if user is None or getattr(user, "role", "") == "admin" else None+ token = (+ (os.environ.get("GITHUB_TOKEN") or None)+ if user is None or getattr(user, "role", "") == "admin"+ else None+ )return ResearchClient(cache_root=get_path_service().get_parse_cache_root() / "research", github_token=token)diff --git a/deeptutor/utils/document_extractor.py b/deeptutor/utils/document_extractor.pyindex e31f7c3b8..1fa8804a2 100644--- a/deeptutor/utils/document_extractor.py+++ b/deeptutor/utils/document_extractor.py@@ -32,10 +32,6 @@ from typing import Anyfrom urllib.parse import unquoteimport zipfile-from defusedxml import ElementTree as DefusedElementTree-from defusedxml.common import DefusedXmlException--from deeptutor.services.rag.file_routing import FileTypeRouterfrom deeptutor.utils.document_images import (EmbeddedImage,build_marker,@@ -44,6 +40,7 @@ from deeptutor.utils.document_images import (extract_pptx_rich,image_index_from_name,)+from deeptutor.utils.file_types import FileTypeRouterlogger = logging.getLogger(__name__)@@ -1091,6 +1088,9 @@ def _parse_xml_member(zf: zipfile.ZipFile, member: str, filename: str) -> Any |raw = zf.read(member)except KeyError:return None+ from defusedxml import ElementTree as DefusedElementTree+ from defusedxml.common import DefusedXmlException+try:return DefusedElementTree.fromstring(raw)except (DefusedElementTree.ParseError, DefusedXmlException) as exc:diff --git a/deeptutor/utils/document_images.py b/deeptutor/utils/document_images.pyindex 2a10969d0..8e8353a9b 100644--- a/deeptutor/utils/document_images.py+++ b/deeptutor/utils/document_images.py@@ -34,8 +34,6 @@ import refrom typing import Anyimport zipfile-from defusedxml import ElementTree as DefusedElementTree-logger = logging.getLogger(__name__)# ---------------------------------------------------------------------------@@ -258,6 +256,8 @@ def _local_name(tag: Any) -> str:def _parse_xml(raw: bytes) -> Any:+ from defusedxml import ElementTree as DefusedElementTree+return DefusedElementTree.fromstring(raw)diff --git a/deeptutor/utils/file_types.py b/deeptutor/utils/file_types.pynew file mode 100644index 000000000..24c57a981--- /dev/null+++ b/deeptutor/utils/file_types.py@@ -0,0 +1,401 @@+"""+File Type Router+================++Centralized file type classification and routing for the RAG pipeline.+Determines the appropriate processing method for each document type.+"""++from dataclasses import dataclass+from enum import Enum+import logging+from pathlib import Path+from typing import List++logger = logging.getLogger(__name__)+++class DocumentType(Enum):+ """Document type classification."""++ PDF = "pdf"+ TEXT = "text"+ MARKDOWN = "markdown"+ DOCX = "docx"+ SPREADSHEET = "spreadsheet"+ PRESENTATION = "presentation"+ EPUB = "epub"+ IMAGE = "image"+ DOCUMENT = "document"+ UNKNOWN = "unknown"+++@dataclass+class FileClassification:+ """Result of file classification."""++ parser_files: List[str]+ text_files: List[str]+ image_files: List[str]+ unsupported: List[str]+++class FileTypeRouter:+ """File type router for the RAG pipeline.++ Classifies files before processing to route them to appropriate handlers:+ - PDF / Office / EPUB files -> parser-based text extraction+ - Text files -> Direct read (fast, simple)+ - Unsupported -> Skip with warning+ """++ PDF_EXTENSIONS = {".pdf"}+ OFFICE_EXTENSIONS = {".docx", ".xlsx", ".pptx"}+ EPUB_EXTENSIONS = {".epub"}+ PARSER_EXTENSIONS = PDF_EXTENSIONS | OFFICE_EXTENSIONS | EPUB_EXTENSIONS++ TEXT_EXTENSIONS = {+ # Plain text & docs+ ".txt",+ ".text",+ ".log",+ ".md",+ ".markdown",+ ".rst",+ ".asciidoc",+ # Data / config+ ".json",+ ".jsonc",+ ".json5",+ ".yaml",+ ".yml",+ ".toml",+ ".csv",+ ".tsv",+ ".ini",+ ".cfg",+ ".conf",+ ".env",+ ".properties",+ # Typesetting+ ".tex",+ ".latex",+ ".bib",+ # JavaScript / TypeScript family+ ".js",+ ".mjs",+ ".cjs",+ ".ts",+ ".mts",+ ".cts",+ ".jsx",+ ".tsx",+ # Web frameworks+ ".vue",+ ".svelte",+ # Python+ ".py",+ # JVM languages+ ".java",+ ".kt",+ ".kts",+ ".scala",+ ".groovy",+ ".gradle",+ # Systems languages+ ".c",+ ".h",+ ".cpp",+ ".cc",+ ".cxx",+ ".hpp",+ ".hh",+ ".hxx",+ ".cs",+ ".go",+ ".rs",+ ".zig",+ ".nim",+ # Apple platforms+ ".swift",+ ".m",+ ".mm",+ # Scripting+ ".rb",+ ".php",+ ".pl",+ ".pm",+ ".lua",+ ".r",+ ".jl",+ ".dart",+ # Functional+ ".hs",+ ".clj",+ ".cljs",+ ".cljc",+ ".ex",+ ".exs",+ ".erl",+ ".ml",+ ".mli",+ ".fs",+ ".fsx",+ ".lisp",+ ".lsp",+ ".scm",+ ".rkt",+ # Web markup / styles+ ".html",+ ".htm",+ ".xml",+ ".svg",+ ".css",+ ".scss",+ ".sass",+ ".less",+ # Smart contracts+ ".sol",+ # Shells / editors+ ".sh",+ ".bash",+ ".zsh",+ ".fish",+ ".ps1",+ ".vim",+ # Query / IDL+ ".sql",+ ".graphql",+ ".gql",+ ".proto",+ # Build / infra+ ".cmake",+ ".mk",+ ".tf",+ ".hcl",+ ".nginxconf",+ ".dockerfile",+ }++ IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".tif"}++ @classmethod+ def get_document_type(cls, file_path: str) -> DocumentType:+ """Classify a single file by its type."""+ ext = cls.get_extension(file_path)++ if ext in cls.PDF_EXTENSIONS:+ return DocumentType.PDF+ elif ext in cls.TEXT_EXTENSIONS:+ return DocumentType.TEXT+ elif ext == ".docx":+ return DocumentType.DOCX+ elif ext == ".xlsx":+ return DocumentType.SPREADSHEET+ elif ext == ".pptx":+ return DocumentType.PRESENTATION+ elif ext in cls.EPUB_EXTENSIONS:+ return DocumentType.EPUB+ elif ext in cls.IMAGE_EXTENSIONS:+ return DocumentType.IMAGE+ elif ext in cls.get_parser_extensions():+ # Formats added by optional rich parsers, such as OpenDocument,+ # legacy Office, mail, archives, audio/video and scientific data.+ return DocumentType.DOCUMENT+ else:+ if cls._is_text_file(file_path):+ return DocumentType.TEXT+ if cls.active_parser_accepts_any_format():+ return DocumentType.DOCUMENT+ return DocumentType.UNKNOWN++ @classmethod+ def _is_text_file(cls, file_path: str, sample_size: int = 8192) -> bool:+ """Detect if a file is text-based by examining its content."""+ try:+ with open(file_path, "rb") as f:+ chunk = f.read(sample_size)++ if b"\x00" in chunk:+ return False++ chunk.decode("utf-8")+ return True+ except (UnicodeDecodeError, IOError, OSError):+ return False++ @classmethod+ def classify_files(cls, file_paths: List[str]) -> FileClassification:+ """Classify a list of files by processing method."""+ parser_files = []+ text_files = []+ image_files = []+ unsupported = []++ for path in file_paths:+ doc_type = cls.get_document_type(path)++ if doc_type in (+ DocumentType.PDF,+ DocumentType.DOCX,+ DocumentType.SPREADSHEET,+ DocumentType.PRESENTATION,+ DocumentType.EPUB,+ DocumentType.DOCUMENT,+ ):+ parser_files.append(path)+ elif doc_type in (DocumentType.TEXT, DocumentType.MARKDOWN):+ text_files.append(path)+ elif doc_type == DocumentType.IMAGE:+ image_files.append(path)+ else:+ unsupported.append(path)++ logger.debug(+ f"Classified {len(file_paths)} files: "+ f"{len(parser_files)} parser, {len(text_files)} text, "+ f"{len(image_files)} image, {len(unsupported)} unsupported"+ )++ return FileClassification(+ parser_files=parser_files,+ text_files=text_files,+ image_files=image_files,+ unsupported=unsupported,+ )++ TEXT_DECODING_CANDIDATES = (+ "utf-8",+ "utf-8-sig",+ "gbk",+ "gb2312",+ "gb18030",+ "latin-1",+ "cp1252",+ )++ @classmethod+ def decode_bytes(cls, data: bytes) -> str:+ """Decode raw bytes using the same fallback chain as read_text_file.++ Used by the chat-attachment extractor so path-based and bytes-based+ callers share one source of truth for supported encodings.+ """+ for encoding in cls.TEXT_DECODING_CANDIDATES:+ try:+ return data.decode(encoding)+ except UnicodeDecodeError:+ continue+ return data.decode("utf-8", errors="replace")++ @classmethod+ async def read_text_file(cls, file_path: str) -> str:+ """Read a text file with automatic encoding detection."""+ for encoding in cls.TEXT_DECODING_CANDIDATES:+ try:+ with open(file_path, "r", encoding=encoding) as f:+ text = f.read()+ break+ except UnicodeDecodeError:+ continue++ else:+ with open(file_path, "rb") as f:+ text = f.read().decode("utf-8", errors="replace")++ if Path(file_path).suffix.lower() == ".bib":+ from deeptutor.utils.bibtex_converter import bibtex_to_markdown++ return bibtex_to_markdown(text, Path(file_path).stem)+ return text++ @classmethod+ def needs_parser(cls, file_path: str) -> bool:+ """Quick check if a single file needs parser processing."""+ doc_type = cls.get_document_type(file_path)+ return doc_type in (+ DocumentType.PDF,+ DocumentType.DOCX,+ DocumentType.SPREADSHEET,+ DocumentType.PRESENTATION,+ DocumentType.EPUB,+ DocumentType.IMAGE,+ DocumentType.DOCUMENT,+ )++ @classmethod+ def is_text_readable(cls, file_path: str) -> bool:+ """Check if a file can be read directly as text."""+ doc_type = cls.get_document_type(file_path)+ return doc_type in (DocumentType.TEXT, DocumentType.MARKDOWN)++ @classmethod+ def get_supported_extensions(cls) -> set[str]:+ """Get the set of all supported file extensions."""+ return cls.get_parser_extensions() | cls.TEXT_EXTENSIONS | cls.IMAGE_EXTENSIONS++ @classmethod+ def get_parser_extensions(cls) -> set[str]:+ """Parser-backed formats accepted by the knowledge-base pipeline.++ The built-in set remains separate because ``document_extractor`` uses+ it for text-only parsing. Lightweight format helpers contribute every+ adapter's current upstream list without importing optional engines.+ """+ from deeptutor.services.parsing.engines.formats import known_parser_formats++ return cls.PARSER_EXTENSIONS | set(known_parser_formats())++ @classmethod+ def active_parser_accepts_any_format(cls) -> bool:+ """Whether the selected engine delegates format detection at runtime."""+ try:+ from deeptutor.services.parsing.engines.factory import get_parser+ from deeptutor.services.parsing.service import get_parse_service++ service = get_parse_service()+ return not get_parser(service.active_engine()).supported_formats()+ except Exception:+ return False++ @classmethod+ def get_extension(+ cls, file_path: str | Path, extensions: set[str] | frozenset[str] | None = None+ ) -> str:+ """Return the longest recognized suffix, including compound suffixes."""+ name = Path(file_path).name.lower()+ candidates = extensions if extensions is not None else cls.get_supported_extensions()+ matches = [+ extension.lower() for extension in candidates if name.endswith(extension.lower())+ ]+ return max(matches, key=len) if matches else Path(file_path).suffix.lower()++ @classmethod+ def has_supported_extension(cls, file_path: str | Path) -> bool:+ """Return True when ``file_path`` has a supported extension.++ The check is case-insensitive so files such as ``Report.PDF`` are+ discovered consistently across upload, CLI, folder sync, and reindex.+ """+ if cls.active_parser_accepts_any_format():+ return True+ supported = cls.get_supported_extensions()+ return cls.get_extension(file_path, supported) in supported++ @classmethod+ def collect_supported_files(cls, directory: str | Path, recursive: bool = False) -> list[Path]:+ """Collect supported files from a directory with case-insensitive suffix matching."""+ root = Path(directory)+ if not root.exists() or not root.is_dir():+ return []++ paths = root.rglob("*") if recursive else root.iterdir()+ return sorted(+ (path for path in paths if path.is_file() and cls.has_supported_extension(path)),+ key=lambda path: str(path).lower(),+ )++ @classmethod+ def get_glob_patterns(cls) -> list[str]:+ """Get glob patterns for file searching."""+ return [f"*{ext}" for ext in sorted(cls.get_supported_extensions())]diff --git a/deeptutor/utils/filenames.py b/deeptutor/utils/filenames.pynew file mode 100644index 000000000..ddf56ce84--- /dev/null+++ b/deeptutor/utils/filenames.py@@ -0,0 +1,12 @@+"""Portable filename normalization for stored user attachments."""++import re++_UNSAFE_CHARS = re.compile(r'[<>:"/\\|?*]')+_CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f]")+++def safe_filename(name: str) -> str:+ """Replace unsafe path / control characters; ``.`` / ``..`` become empty."""+ cleaned = _CONTROL_CHARS.sub("", _UNSAFE_CHARS.sub("_", name or "")).strip().strip(".")+ return cleaneddiff --git a/deeptutor_cli/main.py b/deeptutor_cli/main.pyindex bc37cef22..b6e3a36d6 100644--- a/deeptutor_cli/main.py+++ b/deeptutor_cli/main.py@@ -2,24 +2,22 @@from __future__ import annotations+from importlib import import_modulefrom pathlib import Pathimport sysimport typerfrom deeptutor.logging import configure_logging+from deeptutor.modules.catalog import manifests, module_enabledfrom deeptutor.runtime.mode import RunMode, set_mode-from .book import register as register_bookfrom .chat import register as register_chatfrom .common import build_turn_request, console, maybe_runfrom .config_cmd import register as register_configfrom .doctor import register as register_doctorfrom .init_cmd import register as register_init-from .kb import register as register_kb-from .memory import register as register_memory-from .notebook import register as register_notebook-from .partner import register as register_partner+from .module import register as register_modulefrom .plugin import register as register_pluginfrom .provider_cmd import register as register_providerfrom .session_cmd import register as register_session@@ -36,47 +34,44 @@ app = typer.Typer(add_completion=False,)-partner_app = typer.Typer(help="Manage partners (IM-connected companions).")chat_app = typer.Typer(help="Interactive chat REPL.")-kb_app = typer.Typer(help="Manage knowledge bases.")skill_app = typer.Typer(help="Manage skills and install from hubs (ClawHub, …).")-memory_app = typer.Typer(help="View and manage lightweight memory.")plugin_app = typer.Typer(help="List plugins.")config_app = typer.Typer(help="Inspect and apply configuration.")session_app = typer.Typer(help="Manage shared sessions.")-notebook_app = typer.Typer(help="Manage notebooks and imported markdown records.")provider_app = typer.Typer(help="Manage provider OAuth login.")-book_app = typer.Typer(help="Manage interactive Books (BookEngine).")workspace_app = typer.Typer(help="Manage the user content workspace.")-app.add_typer(partner_app, name="partner")app.add_typer(chat_app, name="chat")-app.add_typer(kb_app, name="kb")app.add_typer(skill_app, name="skill")app.add_typer(skill_app, name="skills") # alias: `deeptutor skills …`-app.add_typer(memory_app, name="memory")app.add_typer(plugin_app, name="plugin")app.add_typer(config_app, name="config")app.add_typer(session_app, name="session")-app.add_typer(notebook_app, name="notebook")app.add_typer(provider_app, name="provider")-app.add_typer(book_app, name="book")app.add_typer(workspace_app, name="workspace")-register_partner(partner_app)register_chat(chat_app)-register_kb(kb_app)register_skill(skill_app)-register_memory(memory_app)register_plugin(plugin_app)register_config(config_app)register_session(session_app)-register_notebook(notebook_app)register_provider(provider_app)-register_book(book_app)register_workspace(workspace_app)+for owner, module in manifests().items():+ if not module_enabled(owner):+ continue+ for command in module["commands"]:+ group = typer.Typer(help=command["help"])+ module_path, attribute = command["register"].split(":", 1)+ getattr(import_module(module_path), attribute)(group)+ app.add_typer(group, name=command["name"])+register_doctor(app)register_init(app)+module_app = typer.Typer(help="Install, remove and inspect optional modules.")+app.add_typer(module_app, name="module")+register_module(module_app)@app.command("run")@@ -145,6 +140,10 @@ def start(),) -> None:"""Launch backend + frontend together. Source installs default to production."""+ from deeptutor.modules.catalog import require_module++ require_module("server")+ require_module("web")from deeptutor.runtime.launcher import start as start_webstart_web(home=home, dev=dev, detach=detach, open_browser=open_browser)@@ -171,6 +170,9 @@ def serve(import asyncioimport sys+ from deeptutor.modules.catalog import require_module++ require_module("server")set_mode(RunMode.SERVER)if port is None:from deeptutor.services.setup import get_backend_port@@ -188,7 +190,7 @@ def serve(except ImportError:console.print("[bold red]Error:[/] API server dependencies not installed.\n"- "Run: pip install -U deeptutor"+ "Run: deeptutor module install server")raise typer.Exit(code=1)diff --git a/deeptutor_cli/module.py b/deeptutor_cli/module.pynew file mode 100644index 000000000..4941581b6--- /dev/null+++ b/deeptutor_cli/module.py@@ -0,0 +1,36 @@+"""Manage the modules in the current DeepTutor environment."""++import json+from pathlib import Path++import typer++from deeptutor.modules.catalog import module_statuses+from deeptutor.modules.lifecycle import change, plan+++def register(app: typer.Typer) -> None:+ @app.command("list")+ def list_modules():+ """Show installed, enabled and ready states separately."""+ typer.echo(json.dumps(module_statuses(), ensure_ascii=False, indent=2))++ def command(action: str):+ def run(+ name: str,+ dry_run: bool = typer.Option(False, "--dry-run"),+ wheelhouse: Path | None = typer.Option(None, "--wheelhouse"),+ ):+ try:+ result = (+ plan(action, name) if dry_run else change(action, name, wheelhouse=wheelhouse)+ )+ except ValueError as exc:+ typer.echo(str(exc), err=True)+ raise typer.Exit(1) from exc+ typer.echo(json.dumps(result, ensure_ascii=False, indent=2))++ return run++ for action in ("install", "uninstall", "enable", "disable"):+ app.command(action)(command(action))diff --git a/docs-for-dev/MODULES.md b/docs-for-dev/MODULES.mdnew file mode 100644index 000000000..c9b27ba2c--- /dev/null+++ b/docs-for-dev/MODULES.md@@ -0,0 +1,167 @@+# Modules and installation++DeepTutor has one source repository and disjoint Python distributions. `deeptutor`+owns the shared turn runtime, CLI and Python SDK. Feature distributions add code+into the same package namespace without overwriting core files. `deeptutor-cli`+is a compatibility metapackage: it depends on core and owns no Python files or+console scripts. `deeptutor[full]` is an installation profile, not a permanent+metapackage that would prevent removing individual applications.++These package changes are prepared in source; the new distribution family must+be published together at the next release. Do not expect the currently published+1.6.15 package to have these boundaries. Local wheel builds are supported now.++## Source checkout++```sh+python -m pip install -r requirements/full.txt+python -m pip install -e . --no-deps+(cd web && npm ci --legacy-peer-deps)+deeptutor module list+deeptutor module disable solve+deeptutor module enable solve+```++In a checkout all source modules are present. `enable` and `disable` exercise the+same assembly rules as wheel installs. `install` and `uninstall` deliberately+require a wheel environment, so they never delete tracked source files. Source+requirements are generated by `python scripts/sync_module_requirements.py`.+Use `--check` in CI to detect drift. `requirements/core.txt` and `server.txt`+are minimal; `full.txt` supplies the ordinary complete source/Docker runtime.++## Independent wheel installation++```sh+python scripts/build_modules.py --output dist/modules+python -m venv /tmp/deeptutor-modules+/tmp/deeptutor-modules/bin/python -m pip install --find-links dist/modules deeptutor+/tmp/deeptutor-modules/bin/deeptutor module install solve --wheelhouse dist/modules+/tmp/deeptutor-modules/bin/deeptutor module install renderer-manim --wheelhouse dist/modules+/tmp/deeptutor-modules/bin/deeptutor module disable solve+/tmp/deeptutor-modules/bin/deeptutor module enable solve+/tmp/deeptutor-modules/bin/deeptutor module uninstall solve --dry-run+/tmp/deeptutor-modules/bin/deeptutor module uninstall solve+```++Use the equivalent `Scripts/python.exe` and `Scripts/deeptutor.exe` on Windows.+Run commands with the same `DEEPTUTOR_HOME` as the application. Python packages+are installed per environment; enabled state lives in+`<home>/data/system/modules.json` and applies to that deployment, not one learner.+`--wheelhouse` supplements the package index with locally built wheels.++Install `server` for the API, then `web` for packaged Web assets. The Web wheel+requires assets produced by `scripts/prepare_web_package.py` for `deeptutor start`;+a source development server uses the checkout's `web/` directory. Build and+release automation prepares Web assets before building the wheel family.++## Ownership and assembly++`deeptutor/modules/manifests/*.json` is the authoritative catalog. Each manifest+owns paths, dependency requirements, turn capabilities, loop extensions, tool+names, API routers and authorization policies, CLI groups, navigation paths and+background service callbacks. Longest matching path wins. Shared protocols and+lightweight context metadata stay in core; feature implementations stay in their+own distribution. The builder rejects overlapping wheel files.++| Module family | Contents |+| --- | --- |+| core | Durable turns, chat, ask-questions, shared tools, CLI/SDK, settings and sessions |+| server / web | API and authentication adapters / packaged Next.js assets |+| solve / questions / research | Planning loop / question generation / research pipeline |+| visualize / renderer-manim | HTML/SVG/chart visualizers / optional Manim pipeline |+| video-lesson / audio-overview | Browser lessons / audio overview generation |+| knowledge / parsing | Retrieval and ingestion / document parsing implementations |+| reading / mastery / books | Reading and watching / guided learning / book application |+| memory / notebook / co-writer / calendar | Optional application services and their routes |+| partners / providers | Companion runtime and channel SDKs / optional model-provider SDKs |+| parser-* | Additional parser dependency distributions, requiring parsing |++Dependencies are explicit and acyclic. For example, reading currently requires+knowledge, parsing, mastery and notebook because its application uses those+stores. Books also requires questions, visualize and mastery for its standard+chapter blocks and selected-source grounding. Optional integrations are listed+separately: Calendar works without Mastery, Research and Questions work without+Knowledge, and Parsing never imports knowledge storage. Selecting an unavailable+integration returns an installation hint. Knowledge Frontier requires both+Research and Knowledge; a tool contribution can declare additional requirements+without forcing those modules onto every use of its owning application.+Disabling a dependency is blocked until its enabled dependents are+disabled. Uninstalling a dependency is blocked while any installed dependent+remains, including disabled dependents. Enabling/installing resolves dependencies+in order. Core cannot be disabled or removed.++The loader does not import absent or disabled capability/loop implementations.+Request schemas are lazy. Loop extensions are instantiated once per turn and+activation is re-evaluated as context changes; instances are never shared across+turns. Managed plugin revocation is still checked. Background start/stop callbacks+remain paired for partial-startup rollback. Existing API authentication policies+remain on the contributed routers; module state is not a permission grant.++`GET /api/modules` requires authentication and exposes installed, enabled and+ready separately. The Runtime settings page displays these states and offline+commands. Sidebar and page access use navigation ownership; API route assembly+also excludes absent modules, including feature-specific paths in shared routers.+Readiness checks package requirements, matching core/module versions and external+executables. Configured provider credentials and service connectivity remain in+the existing settings readiness system.++## Lifecycle guarantees++Official modules share one interpreter. Running application containers hold a+shared environment lease; module changes require an exclusive lease, across+processes. A second lease protects deployment selection when different Python+environments share the same home. Stop CLI turns and API workers before changing packages or selection.+Direct external `pip` commands cannot be prevented by this advisory lock.++Install first resolves dependencies, rejects replacement of an existing package+version, and builds the exact resolved artifacts before modifying the environment.+If installation fails after adding packages, those newly added distributions are+removed, including when saving selection fails. Malformed selection is rejected+before any package mutation. Selection is atomically replaced only after package operations succeed.+Use a new environment or an explicit environment upgrade for dependency conflicts.+This is not an atomic filesystem transaction across a machine crash; standard pip+repair/reinstallation remains the recovery path for an interrupted machine.++Uninstall removes only the selected distribution. Shared dependencies are retained+because other applications may use them. User settings, sessions, notebooks,+knowledge bases, generated artifacts and credentials are never purged. Reinstall+uses the retained data. There is no implicit data-deletion command.++Parser package installation from a running settings/setup session now returns an+offline module command. It no longer upgrades packages beneath active turns.+Model-weight downloads remain background jobs, because they do not alter Python+code. Third-party managed plugins retain their existing isolated environments.++## Worker streaming and cancellation++A worker may advertise `"transport": "ndjson-v1"` in `describe_capability`.+For a run, it emits JSON lines of `{"kind":"event","event":{...}}`, then+`{"kind":"complete"}`. Events are forwarded immediately through the ordinary+turn stream, which owns persistence/replay. EOF without completion, malformed+frames and permission escalation fail the run. Requests, frames, total output,+stderr and execution time have bounds; the consumer queue applies backpressure.+Cancellation closes the process group and waits for cleanup. Legacy one-response+workers remain supported and also stop on cancellation. The learning-echo example+shows both protocols. These workers do not share the host's Python environment.++## Validation++```sh+python scripts/sync_module_requirements.py --check+python -m pytest tests/modules tests/test_packaging_metadata.py+python scripts/build_modules.py --output dist/modules+python scripts/check_module_install.py --wheelhouse dist/modules --extended+```++The install smoke creates a disposable virtual environment, uses a local mock+model (no provider credentials), checks core chat and durable replay, installs+Solve, runs it, uninstalls it, verifies persisted files, checks core again, then+reinstalls Solve. Extended mode installs Parsing, Research and Calendar without+Knowledge or Mastery, exercises parsing and its cache plus independent research+and calendar paths, then removes each module while verifying Solve and retained+data. The source isolation tests also prohibit undeclared imports in a fresh+subprocess for each of the 25 modules and assemble their contributions.+Manim additionally needs system rendering libraries, FFmpeg and+LaTeX. A render and cancellation test should accompany changes to its renderer.+The Web application remains one frontend distribution; independently replaceable+third-party frontend bundles are outside this Python module contract.diff --git a/docs-for-dev/MODULE_REVIEW.md b/docs-for-dev/MODULE_REVIEW.mdnew file mode 100644index 000000000..11c88addb--- /dev/null+++ b/docs-for-dev/MODULE_REVIEW.md@@ -0,0 +1,47 @@+# Module boundary review — 2026-10-28++Reviewed against local `dev` at `e347c0c2e017248d08297c0cf00f5c55f79747fe`.++## Resolved issues++- Parsing imported the knowledge indexing journal even for plain-text parsing.+ Parsing now owns the progress protocol/context; knowledge keeps compatibility+ exports and supplies the journal implementation.+- Research and Questions prepared PageIndex tools without a knowledge base.+ They now prepare these tools only for an explicitly selected, enabled KB.+ Research credentials no longer import the knowledge-source adapter.+- Calendar unconditionally read Mastery storage. Mastery projections are now+ optional; calendar events, practice projections and automations remain usable.+- Knowledge Frontier needs both Research and Knowledge. Its tool contribution+ declares both availability requirements instead of exposing a broken tool.+- Books' standard quiz/visual blocks and source grounding now have explicit+ dependencies. Optional notebook, audio-note and Manim integrations reject+ unavailable modules with actionable hints. Core suggestions/diagnostics work+ without Memory/Knowledge.+- Word/Excel creation and practice imports/exports also need python-docx and+ openpyxl. These remain core dependencies, independent of Parsing.+- Malformed selection is rejected before pip runs. A failed selection write after+ installation rolls back added packages. Enable rejects mismatched versions.+ Locks cover both the interpreter and shared deployment state.+- Installation, plugin and Manim cancellation share process-tree cleanup;+ Windows uses taskkill /T /F instead of killing only the parent.++## Validation++- Expanded Python regression: 3,979 passed, 61 skipped.+- Final cancellation/module/plugin/renderer/launcher checks: 236 passed.+- Fresh-process assembly for all 25 modules prohibits imports of unrelated+ modules. Independent Core, Parsing, Research, Question, Calendar and API paths+ are exercised; Parsing includes a repeated cache read.+- 26 wheels built with no overlapping installed files.+- Disposable wheel environment: core chat and durable replay, Word/Excel file+ generation, Solve install/run/uninstall/reinstall, independent Parsing,+ Research and Calendar, then individual removal while Solve remains usable.+ Retained data hashes and pip check passed. Model responses use a local fixture.+- Web typecheck and module tests passed; production Web build was validated during+ implementation. Architecture/import contracts, Ruff, generated requirements,+ repository hygiene and README structure checks passed.++Executed locally on macOS / Python 3.13. Windows cleanup command construction is+covered by tests; an actual Windows host was not used. CI has an extended wheel+lifecycle job for Python 3.11 and 3.13. No packages were published.diff --git a/examples/plugins/learning_echo/learning_echo/worker.py b/examples/plugins/learning_echo/learning_echo/worker.pyindex 1f3c7559b..ba48fbe81 100644--- a/examples/plugins/learning_echo/learning_echo/worker.py+++ b/examples/plugins/learning_echo/learning_echo/worker.py@@ -26,7 +26,12 @@ def main() -> None:response = handle_http(request.get("http") or {})else:response = {"error": f"unknown operation: {operation}"}- print(json.dumps(response, ensure_ascii=False))+ if operation == "run_capability" and request.get("transport") == "ndjson-v1":+ for event in response["events"]:+ print(json.dumps({"kind": "event", "event": event}), flush=True)+ print(json.dumps({"kind": "complete"}), flush=True)+ else:+ print(json.dumps(response, ensure_ascii=False))def describe_tool() -> dict[str, Any]:@@ -56,6 +61,7 @@ def execute_tool(arguments: dict[str, Any]) -> dict[str, Any]:def describe_capability() -> dict[str, Any]:return {+ "transport": "ndjson-v1","permissions": {},"capability": {"name": "learning_echo_capability",diff --git a/packaging/deeptutor-cli/pyproject.toml b/packaging/deeptutor-cli/pyproject.tomlindex feb082ed5..8dc597715 100644--- a/packaging/deeptutor-cli/pyproject.toml+++ b/packaging/deeptutor-cli/pyproject.toml@@ -1,103 +1,11 @@[build-system]requires = ["setuptools>=61.0", "wheel"]build-backend = "setuptools.build_meta"-[project]name = "deeptutor-cli"-dynamic = ["version"]-description = "CLI-only distribution for DeepTutor"-# Match the main package: Python 3.14 is supported, while the forward cap keeps-# future interpreters out until compiled dependencies publish compatible wheels.+version = "1.6.15"+description = "Compatibility install for the minimal DeepTutor CLI"requires-python = ">=3.11,<3.15"-readme = "README.md"-license = {text = "Apache-2.0"}-dependencies = [- "psutil>=5.9.0,<8.0.0",- "pywin32; sys_platform == 'win32'", # MinerU Job Object ownership- "PyYAML>=6.0",- "jinja2>=3.1.0",- "openai>=1.30.0",- "tiktoken>=0.5.0",- "aiohttp>=3.9.4",- "httpx>=0.27.0",- "requests>=2.32.2",- "ddgs>=9.9.1",- "nest_asyncio>=1.5.8",- "tenacity>=8.0.0",- "pydantic>=2.0.0",- "pydantic-settings>=2.0.0",- "packaging>=24.2",- "jsonschema>=4.20.0,<5.0.0",- "aiosqlite>=0.19.0",- "typer>=0.9.0",- "rich>=13.0.0",- "prompt_toolkit>=3.0.36",- "pyte>=0.8.1",- # Imported eagerly by the shared LLM provider stack. These must remain- # core dependencies: even `deeptutor --help` imports that stack.- "loguru>=0.7.3,<1.0.0",- "json-repair>=0.57.0,<1.0.0",- # MCP client. This distribution ships the configurable MCP tool surface, so- # it needs the client without an optional extra (issue #792).- "mcp>=1.26.0,<2.0.0",- "pageindex>=0.2.10,<0.3.0",- # The shared partner onboarding CLI renders QR codes on a plain CLI install.- "qrcode>=7.4.0,<9.0.0",- # IANA time zone data for `zoneinfo`; Windows has no system database.- "tzdata>=2024.1",- "anthropic>=0.30.0",- "dashscope>=1.14.0",- "perplexityai>=0.1.0",- "oauth-cli-kit>=0.1.1",- "llama-index>=0.14.12",- # PyStemmer 2.x has no Python 3.14 wheel; the runtime falls back to vector- # retrieval when this optional BM25 integration is absent.- "bm25s>=0.3.14,<0.4.0", # Legacy page lookup without optional PyStemmer- "llama-index-retrievers-bm25>=0.7.1,<0.8.0; python_version < '3.14'",- # FAISS vector store: ANN retrieval replacing SimpleVectorStore brute force for- # large KBs (issue #552); imported lazily with SimpleVectorStore fallback.- "llama-index-vector-stores-faiss>=0.4.0,<1.0.0",- "faiss-cpu>=1.8.0,<2.0.0; python_version < '3.14'",- "faiss-cpu>=1.12.0,<2.0.0; python_version >= '3.14'",- "PyMuPDF>=1.26.0",- "Pillow>=10.0.0",- "numpy>=1.24.0,<3.0.0",- "arxiv>=2.0.0",- "python-docx>=1.1.0",- "openpyxl>=3.1.0",- "python-pptx>=1.0.0",- "pypdf>=4.0.0",- "pdfplumber>=0.11.0",- "reportlab>=4.0.0",- "defusedxml>=0.7.1",- "youtube-transcript-api>=1.2.0,<2.0.0",-]--[project.scripts]-deeptutor = "deeptutor_cli.main:main"-+dependencies = ["deeptutor==1.6.15"][tool.setuptools]-package-dir = {"" = "../.."}-include-package-data = false--[tool.setuptools.dynamic]-version = {attr = "deeptutor.__version__.__version__"}--[tool.setuptools.packages.find]-where = ["../.."]-include = ["deeptutor*", "deeptutor_cli*"]-exclude = ["deeptutor_web*"]--# This distribution includes the shared agent implementations. Keep their-# runtime prompt/config assets in the wheel as the full distribution does.-[tool.setuptools.package-data]-deeptutor = [- "**/*.yaml",- "**/*.yml",- "**/*.md",- "**/*.json",- "**/*.sh",- "**/*.j2",- "**/*.jinja",-]-deeptutor_cli = ["**/*.md"]+packages = []diff --git a/pyproject.toml b/pyproject.tomlindex 2f52f9ca3..011dea258 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -17,7 +17,6 @@ requires-python = ">=3.11,<3.15"readme = "README.md"license = {text = "Apache-2.0"}dependencies = [- # Core runtime"PyYAML>=6.0","jinja2>=3.1.0","openai>=1.30.0",@@ -36,289 +35,61 @@ dependencies = ["typer>=0.9.0","rich>=13.0.0","prompt_toolkit>=3.0.36",- "pyte>=0.8.1", # in-memory terminal emulator: scrape Claude Code's /model TUI on sync- # MCP client. Core rather than a `partners`-only extra (issue #792): the- # default chat/tool surface includes configurable MCP servers, so a plain- # install must be able to connect them without an optional extra.+ "pyte>=0.8.1","mcp>=1.26.0,<2.0.0",- "pageindex>=0.2.10,<0.3.0",- # Partner channel QR onboarding (WeChat, WeCom, Feishu). Same reasoning as- # `mcp` above: scan-based onboarding is part of the default partner setup- # surface, it is pure Python with no compiled or system dependencies, and- # without it the browser renders no code at all — the operator sees a- # button that does nothing, with no error to explain why.- "qrcode>=7.4.0,<9.0.0",- # IANA time zone database for `zoneinfo`. Windows ships none, so without- # it every named zone (even "UTC") is unknown there and usage statistics,- # practice reviews and cron schedules reject every timezone they are given.- # On Linux/macOS `zoneinfo` keeps preferring the system database."tzdata>=2024.1",- # Full app dependencies included by default for `pip install deeptutor`.- "anthropic>=0.30.0",- "dashscope>=1.14.0",- "perplexityai>=0.1.0",- "oauth-cli-kit>=0.1.1",- "llama-index>=0.14.12",- # The current BM25 integration pins PyStemmer <3, whose 2.x line has no- # Python 3.14 wheels. Skip it there so ordinary installs never require a C- # compiler; the retriever already falls back to vector search when absent.- "bm25s>=0.3.14,<0.4.0", # Legacy page lookup without optional PyStemmer- "llama-index-retrievers-bm25>=0.7.1,<0.8.0; python_version < '3.14'",- # FAISS vector store: vectorized ANN retrieval that replaces SimpleVectorStore's- # brute-force per-query scan for large knowledge bases (issue #552). The- # pipeline imports it lazily and falls back to SimpleVectorStore if absent.- "llama-index-vector-stores-faiss>=0.4.0,<1.0.0",- "faiss-cpu>=1.8.0,<2.0.0; python_version < '3.14'",- "faiss-cpu>=1.12.0,<2.0.0; python_version >= '3.14'",- "PyMuPDF>=1.26.0",- "Pillow>=10.0.0",- "numpy>=1.24.0,<3.0.0",- "arxiv>=2.0.0",- "python-docx>=1.1.0",- "openpyxl>=3.1.0",- "python-pptx>=1.0.0",- "pypdf>=4.0.0",- "pdfplumber>=0.11.0",- "reportlab>=4.0.0",- "defusedxml>=0.7.1",- "youtube-transcript-api>=1.2.0,<2.0.0",- "fastapi>=0.100.0",- "uvicorn[standard]>=0.24.0",- "websockets>=12.0",- "python-multipart>=0.0.6",- "bcrypt>=4.0.0",- "python-jose[cryptography]>=3.3.0",- "pocketbase>=0.12.0",- "redis>=5.0.0,<7.0.0","loguru>=0.7.3,<1.0.0","json-repair>=0.57.0,<1.0.0",- "croniter>=6.0.0,<7.0.0",- "python-dateutil>=2.9.0,<3.0.0",- # Process-tree memory readings and Windows MinerU worker ownership."psutil>=5.9.0,<8.0.0",- "pywin32; sys_platform == 'win32'", # MinerU Job Object ownership+ "python-docx>=1.1.0",+ "openpyxl>=3.1.0"][project.scripts]deeptutor = "deeptutor_cli.main:main"-deeptutor-export-frontend-contracts = "deeptutor.api.contracts.export:main"--[project.entry-points."deeptutor.reading_extensions"]-read_aloud = "deeptutor.reading.read_aloud:ReadAloudExtension"-guided_learning = "deeptutor.reading.study_guidance:StudyGuidanceExtension"-vocabulary = "deeptutor.reading.vocabulary:VocabularyExtension"-quiz = "deeptutor.reading.quiz:ReadingQuizExtension"-translation = "deeptutor.reading.translation:TranslationExtension"[project.optional-dependencies]-# Compatibility extra for source installs and older docs. These packages are-# already included in the public `deeptutor` wheel; the local CLI-only project-# under `packaging/deeptutor-cli` uses the same list without Web assets/server deps.-cli = [- "psutil>=5.9.0,<8.0.0",- "pywin32; sys_platform == 'win32'", # MinerU Job Object ownership- "packaging>=24.2",- # LLM provider SDKs- "anthropic>=0.30.0",- "dashscope>=1.14.0",- "perplexityai>=0.1.0",- "oauth-cli-kit>=0.1.1",- "pageindex>=0.2.10,<0.3.0",- # RAG (LlamaIndex)- "llama-index>=0.14.12",- "bm25s>=0.3.14,<0.4.0", # Legacy page lookup without optional PyStemmer- "llama-index-retrievers-bm25>=0.7.1,<0.8.0; python_version < '3.14'",- # FAISS vector store: vectorized ANN retrieval that replaces SimpleVectorStore's- # brute-force per-query scan for large knowledge bases (issue #552). The- # pipeline imports it lazily and falls back to SimpleVectorStore if absent.- "llama-index-vector-stores-faiss>=0.4.0,<1.0.0",- "faiss-cpu>=1.8.0,<2.0.0; python_version < '3.14'",- "faiss-cpu>=1.12.0,<2.0.0; python_version >= '3.14'",- "PyMuPDF>=1.26.0",- "Pillow>=10.0.0",- "numpy>=1.24.0,<3.0.0",- "arxiv>=2.0.0",- # Document text extraction (chat attachments) + office-skill authoring libs- "python-docx>=1.1.0",- "openpyxl>=3.1.0",- "python-pptx>=1.0.0",- "pypdf>=4.0.0",- "pdfplumber>=0.11.0",- "reportlab>=4.0.0",- "defusedxml>=0.7.1",- "youtube-transcript-api>=1.2.0,<2.0.0",-]--# CodeBuddy chat works over HTTP with the login state the IDE plugin / CLI-# already stores. This extra adds the Agent SDK (a ~130 MB bundled headless-# CLI) for in-app browser login and CLI-driven agent tools.-# Upper-bounded on purpose: the provider probes the SDK for its turn-limit-# and permission-mode kwargs, and a minor bump that renames them would make-# every options build fail — codebuddy_provider fails closed with a clear-# message rather than running the agent unrestricted. The floor tracks the-# published series: there is no 0.1.24 on PyPI (0.1.x stops at 0.1.19), so the-# old `>=0.1.24,<0.2` range was unsatisfiable and any resolver rejected it.-# Not in `all` — it vendors a ~130 MB headless CLI and chat works over plain-# HTTP without it.+# Optional modules own their code and dependencies. Full is an installation profile.+cli = []codebuddy = ["codebuddy-agent-sdk>=0.3,<0.4"]--# Native YouTube playback has no Python dependency. This small, optional-# adapter enables transcript-grounded learning when public captions exist.-video-learning = ["youtube-transcript-api>=1.0.0,<2.0.0"]--# Microsoft Edge read-aloud voices as a free, keyless TTS provider.+video-learning = ["deeptutor-reading==1.6.15"]edge-tts = ["edge-tts>=7.0,<8.0"]-# Compatibility extra for optional video lesson narration.-video-lesson = ["deeptutor[edge-tts]"]--# Compatibility extra for source installs and older docs. These packages are-# already included in the public `deeptutor` wheel.-server = [- "deeptutor[cli]",- "fastapi>=0.100.0",- "uvicorn[standard]>=0.24.0",- "websockets>=12.0",- "python-multipart>=0.0.6",- "bcrypt>=4.0.0",- "python-jose[cryptography]>=3.3.0",- "pocketbase>=0.12.0",- "redis>=5.0.0,<7.0.0",- "loguru>=0.7.3,<1.0.0",- "json-repair>=0.57.0,<1.0.0",- "croniter>=6.0.0,<7.0.0",- "python-dateutil>=2.9.0,<3.0.0",- "psutil>=5.9.0,<8.0.0",-]--# Partner channel SDKs. Mirrors requirements/partners.txt.-# Partners run on the chat agent loop, so there is no engine here — just the-# IM platform SDKs. The MCP client used for deferred tools is a core dependency-# (see `mcp` above), not a partners-only one.-partners = [- "deeptutor[server]",- "python-telegram-bot[socks]>=22.6,<23.0",- "wecom-aibot-sdk>=1.0.8,<2.0.0",- "lark-oapi>=1.5.0,<2.0.0",- "dingtalk-stream>=0.24.0,<1.0.0",- "slack-sdk>=3.39.0,<4.0.0",- "slackify-markdown>=0.2.0,<1.0.0",- "qq-botpy>=1.2.0,<2.0.0",- "python-socketio>=5.16.0,<6.0.0",- "msgpack>=1.1.0,<2.0.0",- "python-socks[asyncio]>=2.8.0,<3.0.0",- "socksio>=1.0.0,<2.0.0",- "websocket-client>=1.9.0,<2.0.0",- "zulip>=0.8.0,<1.0.0",- # slack-sdk Socket Mode + napcat need the async `websockets` lib — pin it- # explicitly instead of relying on dingtalk-stream/lark-oapi transitives.- "websockets>=12.0",- # napcat (OneBot v11) media downloads- "aiohttp>=3.10.0,<4.0.0",- # msteams Bot Framework token validation- "PyJWT[crypto]>=2.8.0,<3.0.0",-]--# Optional document-parsing engines for the shared parse layer-# (deeptutor/services/parsing). MinerU is an external CLI / hosted API and is-# not a pip dependency. Engines import lazily, so these stay opt-in and an-# absent engine simply reports unavailable in Settings → Document Parsing.-parse-markitdown = ["markitdown[all]>=0.1.7"]-# Docling's base package intentionally leaves some format backends as extras.-# Install all input-format dependencies so DeepTutor can honor the complete-# upstream format list. Legacy Office needs LibreOffice and video needs ffmpeg-# on the host in addition to these Python packages.-parse-docling = [- "docling[xbrl]>=2.123.1",- "docling-slim[format-iwork,format-opendocument,format-video]>=2.123.1",-]-# Current PyMuPDF4LLM includes CPU-only layout/OCR and image extraction on its-# public conversion path. Keep it upgradeable so format and layout gains land-# without a DeepTutor-side major-version ceiling.-parse-pymupdf4llm = ["pymupdf4llm>=1.28.2"]-parse-liteparse = ["liteparse>=2.14.2"]-parse = [- "deeptutor[parse-markitdown]",- "deeptutor[parse-docling]",- "deeptutor[parse-pymupdf4llm]",- "deeptutor[parse-liteparse]",-]--# Legacy alias kept for one release: `pip install deeptutor[tutorbot]`.+video-lesson = ["deeptutor-video-lesson==1.6.15", "edge-tts>=7.0,<8.0"]+server = ["deeptutor-server==1.6.15"]+partners = ["deeptutor-partners==1.6.15"]+parse-markitdown = ["deeptutor-parser-markitdown==1.6.15"]+parse-docling = ["deeptutor-parser-docling==1.6.15"]+parse-pymupdf4llm = ["deeptutor-parser-pymupdf4llm==1.6.15"]+parse-liteparse = ["deeptutor-parser-liteparse==1.6.15"]+parse = ["deeptutor[parse-markitdown]", "deeptutor[parse-docling]", "deeptutor[parse-pymupdf4llm]", "deeptutor[parse-liteparse]"]tutorbot = ["deeptutor[partners]"]--# Matrix (Element) channel for partners. Mirrors requirements/matrix.txt.-# Default Matrix install is non-E2EE so it works without libolm/python-olm.-matrix = [- "matrix-nio>=0.25.2,<1.0.0",- "mistune>=3.0.0,<4.0.0",- "nh3>=0.2.18,<1.0.0",-]--# Optional Matrix E2EE addon. Mirrors requirements/matrix-e2e.txt and requires libolm.-matrix-e2e = [- "deeptutor[matrix]",- "matrix-nio[e2e]>=0.25.2,<1.0.0",-]--# Math Animator addon (Manim). Mirrors requirements/math-animator.txt.-# System prerequisites (installed outside pip): LaTeX, pkg-config, cairo, cmake, ffmpeg.-math-animator = ["manim>=0.19.0"]--# GraphRAG knowledge-base engine (microsoft/graphrag). Optional, heavy-# (LiteLLM + lancedb + graspologic) and kept out of `all` so it stays a-# deliberate opt-in. The pipeline imports lazily and the adapter targets the-# 3.x API (see services/rag/pipelines/graphrag/engine.py). Every graphrag 3.x-# release is capped at python <3.14; the `python_version` marker mirrors that-# so on 3.14+ the extra resolves to a no-op instead of an unsatisfiable hard-# dep — otherwise pip backtracks deeptutor to the last extra-free version-# (1.4.5) and silently downgrades. Floor is 3.0.1 (3.0.0/3.0.3 were yanked).+matrix = ["matrix-nio>=0.25.2,<1.0.0", "mistune>=3.0.0,<4.0.0", "nh3>=0.2.18,<1.0.0"]+matrix-e2e = ["deeptutor[matrix]", "matrix-nio[e2e]>=0.25.2,<1.0.0"]+math-animator = ["deeptutor-renderer-manim==1.6.15"]graphrag = ["graphrag>=3.0.1,<4.0.0; python_version < '3.14'"]--# Built-in LightRAG provider. The exact release is intentional: the adapter-# isolates a private source-resolver seam and locks it with smoke tests.-# MinerU remains an independently selected DeepTutor parser and is not a-# transitive dependency of this extra.rag-lightrag = ["lightrag-hku==1.5.7"]--# Optional cross-encoder reranker for the default LlamaIndex engine. The-# sentence-transformers/torch stack is heavy and model-dependent, so it stays-# out of `all`; retrieval lazily falls back to embedding-only ranking when the-# package or configured model is unavailable.rag-rerank = ["sentence-transformers>=3.0.0,<6.0.0; python_version < '3.14'"]--# Optional request screening (rate limit, IP allow/deny lists, attack-pattern-# scan of path, query and headers). Off unless system.json `security_guard`-# is enabled; see docs-for-user/SECURITY_GUARD.md. Mirrors-# requirements/guard.txt. Docker: DEEPTUTOR_EXTRAS=guard.guard = ["fastapi-guard>=8.1.1,<9.0.0"]--# Dev/test tooling. Mirrors requirements/dev.txt.-dev = [- "deeptutor[server]",- "pytest>=7.0.0",- "pytest-asyncio>=0.23.0",- "pre-commit>=3.0.0",- "safety<3.0.0",- "bandit>=1.8.0",- "import-linter>=2.1.0,<3.0.0",- # Test fixture builders for document-loader tests. Runtime pulls these via- # cli/server, but dev keeps them explicit for pytest collection.- "python-docx>=1.1.0",- "openpyxl>=3.1.0",- "python-pptx>=1.0.0",- "pypdf>=4.0.0",- "defusedxml>=0.7.1",-]--# Everything: server + partners + non-E2EE matrix + math-animator + dev tools.-all = [- "deeptutor[partners]",- "deeptutor[matrix]",- "deeptutor[math-animator]",- "deeptutor[dev]",- "deeptutor[video-learning]",- "deeptutor[edge-tts]",-]+dev = ["deeptutor[server]", "pytest>=7.0.0", "pytest-asyncio>=0.23.0", "pre-commit>=3.0.0", "safety<3.0.0", "bandit>=1.8.0", "import-linter>=2.1.0,<3.0.0", "python-docx>=1.1.0", "openpyxl>=3.1.0", "python-pptx>=1.0.0", "pypdf>=4.0.0", "defusedxml>=0.7.1"]+all = ["deeptutor[full,math-animator,dev]"]+audio-overview = ["deeptutor-audio-overview==1.6.15"]+solve = ["deeptutor-solve==1.6.15"]+reading = ["deeptutor-reading==1.6.15"]+memory = ["deeptutor-memory==1.6.15"]+providers = ["deeptutor-providers==1.6.15"]+questions = ["deeptutor-questions==1.6.15"]+notebook = ["deeptutor-notebook==1.6.15"]+web = ["deeptutor-web==1.6.15"]+parsing = ["deeptutor-parsing==1.6.15"]+books = ["deeptutor-books==1.6.15"]+research = ["deeptutor-research==1.6.15"]+visualize = ["deeptutor-visualize==1.6.15"]+renderer-manim = ["deeptutor-renderer-manim==1.6.15"]+calendar = ["deeptutor-calendar==1.6.15"]+knowledge = ["deeptutor-knowledge==1.6.15"]+co-writer = ["deeptutor-co-writer==1.6.15"]+mastery = ["deeptutor-mastery==1.6.15"]+full = ["deeptutor-audio-overview==1.6.15", "deeptutor-solve==1.6.15", "deeptutor-server==1.6.15", "deeptutor-reading==1.6.15", "deeptutor-partners==1.6.15", "deeptutor-memory==1.6.15", "deeptutor-providers==1.6.15", "deeptutor-questions==1.6.15", "deeptutor-notebook==1.6.15", "deeptutor-web==1.6.15", "deeptutor-video-lesson==1.6.15", "deeptutor-parsing==1.6.15", "deeptutor-books==1.6.15", "deeptutor-research==1.6.15", "deeptutor-visualize==1.6.15", "deeptutor-calendar==1.6.15", "deeptutor-knowledge==1.6.15", "deeptutor-co-writer==1.6.15", "deeptutor-mastery==1.6.15"][tool.setuptools]include-package-data = truediff --git a/requirements.txt b/requirements.txtindex b24e9391c..d60323677 100644--- a/requirements.txt+++ b/requirements.txt@@ -1,22 +1,2 @@-# ============================================-# DeepTutor Python Dependencies (Runtime Bundle)-# ============================================-# Python >= 3.11 required-#-# Single source of truth: pyproject.toml `[project.optional-dependencies]`.-# Files under requirements/ mirror those extras for Docker/CI installs that-# don't yet have access to pyproject.toml + source code.-#-# Preferred installs:-# pip install deeptutor # Full app (public wheel)-# pip install deeptutor-cli # CLI-only public wheel-# pip install -e . # Source checkout-# pip install -e ".[partners]" # Server + partner channel SDKs-# pip install -e ".[matrix]" # Matrix channel for partners-# pip install -e ".[math-animator]" # Manim animation engine (addon)-# pip install -e ".[dev]" # Server + dev/test tools-# pip install -e ".[all]" # Everything-#-# This file installs the full server runtime (CLI + API + partners).---r requirements/partners.txt+# Source/Docker full profile. Generated module groups own dependency versions.+-r requirements/full.txtdiff --git a/requirements/cli.txt b/requirements/cli.txtindex 0a545bd71..84359d5eb 100644--- a/requirements/cli.txt+++ b/requirements/cli.txt@@ -1,90 +1,2 @@-# ============================================-# DeepTutor CLI — Full Dependencies-# ============================================-# Mirrors pyproject.toml `[project.optional-dependencies].cli` plus core deps.-# Keep in sync with pyproject.toml when adding/updating dependencies.-#-# Public install: pip install deeptutor-cli-# Source compatibility: pip install -e ".[cli]"-# Use this file for Docker/CI when pyproject.toml/source code aren't yet available.--# --- Config & templating ----PyYAML>=6.0-jinja2>=3.1.0--# --- LLM ----openai>=1.30.0-tiktoken>=0.5.0--# --- LLM provider SDKs ----anthropic>=0.30.0-dashscope>=1.14.0-perplexityai>=0.1.0-oauth-cli-kit>=0.1.1; python_version >= "3.11"--# --- HTTP clients ----aiohttp>=3.9.4-httpx>=0.27.0-requests>=2.32.2--# --- Async helpers ----nest_asyncio>=1.5.8-tenacity>=8.0.0--# --- Data models & storage ----pydantic>=2.0.0-pydantic-settings>=2.0.0-packaging>=24.2-jsonschema>=4.20.0,<5.0.0-aiosqlite>=0.19.0--# --- RAG (LlamaIndex) ----llama-index>=0.14.12-# PyStemmer 2.x has no Python 3.14 wheels. LlamaIndex falls back to vector-# retrieval when this optional BM25 integration is unavailable.-bm25s>=0.3.14,<0.4.0-llama-index-retrievers-bm25>=0.7.1,<0.8.0; python_version < "3.14"-# FAISS vector store: ANN retrieval replacing SimpleVectorStore brute force for-# large KBs (issue #552); imported lazily with SimpleVectorStore fallback.-llama-index-vector-stores-faiss>=0.4.0,<1.0.0-faiss-cpu>=1.8.0,<2.0.0; python_version < "3.14"-faiss-cpu>=1.12.0,<2.0.0; python_version >= "3.14"-PyMuPDF>=1.26.0-psutil>=5.9.0,<8.0.0-pywin32; sys_platform == "win32"-Pillow>=10.0.0-numpy>=1.24.0,<3.0.0-arxiv>=2.0.0--# --- Document text extraction (chat attachments) + office-skill authoring libs ----python-docx>=1.1.0-openpyxl>=3.1.0-python-pptx>=1.0.0-pypdf>=4.0.0-pdfplumber>=0.11.0-reportlab>=4.0.0-defusedxml>=0.7.1-youtube-transcript-api>=1.2.0,<2.0.0--# --- Web search ----ddgs>=9.9.1--# --- CLI framework ----typer>=0.9.0-rich>=13.0.0-prompt_toolkit>=3.0.36-pyte>=0.8.1--# --- Shared LLM runtime (imported by the CLI entry point) ----loguru>=0.7.3,<1.0.0-json-repair>=0.57.0,<1.0.0--# --- MCP client (configurable deferred tools; core, not partners-only) ----mcp>=1.26.0,<2.0.0-pageindex>=0.2.10,<0.3.0--# --- Partner channel QR onboarding (WeChat, WeCom, Feishu; core) ----qrcode>=7.4.0,<9.0.0--# --- IANA time zone data for zoneinfo (Windows has no system database) ----tzdata>=2024.1+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r core.txtdiff --git a/requirements/core.txt b/requirements/core.txtnew file mode 100644index 000000000..09a76a960--- /dev/null+++ b/requirements/core.txt@@ -0,0 +1,27 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+PyYAML>=6.0+jinja2>=3.1.0+openai>=1.30.0+tiktoken>=0.5.0+aiohttp>=3.9.4+httpx>=0.27.0+requests>=2.32.2+ddgs>=9.9.1+nest_asyncio>=1.5.8+tenacity>=8.0.0+pydantic>=2.0.0+pydantic-settings>=2.0.0+packaging>=24.2+jsonschema>=4.20.0,<5.0.0+aiosqlite>=0.19.0+typer>=0.9.0+rich>=13.0.0+prompt_toolkit>=3.0.36+pyte>=0.8.1+mcp>=1.26.0,<2.0.0+tzdata>=2024.1+loguru>=0.7.3,<1.0.0+json-repair>=0.57.0,<1.0.0+psutil>=5.9.0,<8.0.0+python-docx>=1.1.0+openpyxl>=3.1.0diff --git a/requirements/full.txt b/requirements/full.txtnew file mode 100644index 000000000..ba99aa363--- /dev/null+++ b/requirements/full.txt@@ -0,0 +1,20 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r modules/audio-overview.txt+-r modules/books.txt+-r modules/calendar.txt+-r modules/co-writer.txt+-r modules/knowledge.txt+-r modules/mastery.txt+-r modules/memory.txt+-r modules/notebook.txt+-r modules/parsing.txt+-r modules/partners.txt+-r modules/providers.txt+-r modules/questions.txt+-r modules/reading.txt+-r modules/research.txt+-r modules/server.txt+-r modules/solve.txt+-r modules/video-lesson.txt+-r modules/visualize.txt+-r modules/web.txtdiff --git a/requirements/modules/audio-overview.txt b/requirements/modules/audio-overview.txtnew file mode 100644index 000000000..b024ae133--- /dev/null+++ b/requirements/modules/audio-overview.txt@@ -0,0 +1,3 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+-r knowledge.txtdiff --git a/requirements/modules/books.txt b/requirements/modules/books.txtnew file mode 100644index 000000000..5384f2cbd--- /dev/null+++ b/requirements/modules/books.txt@@ -0,0 +1,7 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+-r knowledge.txt+-r parsing.txt+-r questions.txt+-r visualize.txt+-r mastery.txtdiff --git a/requirements/modules/calendar.txt b/requirements/modules/calendar.txtnew file mode 100644index 000000000..ad617323c--- /dev/null+++ b/requirements/modules/calendar.txt@@ -0,0 +1,4 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+croniter>=6.0.0,<7.0.0+python-dateutil>=2.9.0,<3.0.0diff --git a/requirements/modules/co-writer.txt b/requirements/modules/co-writer.txtnew file mode 100644index 000000000..b024ae133--- /dev/null+++ b/requirements/modules/co-writer.txt@@ -0,0 +1,3 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+-r knowledge.txtdiff --git a/requirements/modules/knowledge.txt b/requirements/modules/knowledge.txtnew file mode 100644index 000000000..cafbe37ea--- /dev/null+++ b/requirements/modules/knowledge.txt@@ -0,0 +1,11 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+-r parsing.txt+pageindex>=0.2.10,<0.3.0+llama-index>=0.14.12+bm25s>=0.3.14,<0.4.0+llama-index-retrievers-bm25>=0.7.1,<0.8.0; python_version < '3.14'+llama-index-vector-stores-faiss>=0.4.0,<1.0.0+faiss-cpu>=1.8.0,<2.0.0; python_version < '3.14'+faiss-cpu>=1.12.0,<2.0.0; python_version >= '3.14'+numpy>=1.24.0,<3.0.0diff --git a/requirements/modules/mastery.txt b/requirements/modules/mastery.txtnew file mode 100644index 000000000..b024ae133--- /dev/null+++ b/requirements/modules/mastery.txt@@ -0,0 +1,3 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+-r knowledge.txtdiff --git a/requirements/modules/memory.txt b/requirements/modules/memory.txtnew file mode 100644index 000000000..9b2f6702e--- /dev/null+++ b/requirements/modules/memory.txt@@ -0,0 +1,2 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txtdiff --git a/requirements/modules/notebook.txt b/requirements/modules/notebook.txtnew file mode 100644index 000000000..9b2f6702e--- /dev/null+++ b/requirements/modules/notebook.txt@@ -0,0 +1,2 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txtdiff --git a/requirements/modules/parser-docling.txt b/requirements/modules/parser-docling.txtnew file mode 100644index 000000000..0ea396806--- /dev/null+++ b/requirements/modules/parser-docling.txt@@ -0,0 +1,5 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+-r parsing.txt+docling[xbrl]>=2.123.1+docling-slim[format-iwork,format-opendocument,format-video]>=2.123.1diff --git a/requirements/modules/parser-liteparse.txt b/requirements/modules/parser-liteparse.txtnew file mode 100644index 000000000..bb345f5e4--- /dev/null+++ b/requirements/modules/parser-liteparse.txt@@ -0,0 +1,4 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+-r parsing.txt+liteparse>=2.14.2diff --git a/requirements/modules/parser-markitdown.txt b/requirements/modules/parser-markitdown.txtnew file mode 100644index 000000000..44fc5b9d8--- /dev/null+++ b/requirements/modules/parser-markitdown.txt@@ -0,0 +1,4 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+-r parsing.txt+markitdown[all]>=0.1.7diff --git a/requirements/modules/parser-pymupdf4llm.txt b/requirements/modules/parser-pymupdf4llm.txtnew file mode 100644index 000000000..475d4a96a--- /dev/null+++ b/requirements/modules/parser-pymupdf4llm.txt@@ -0,0 +1,4 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+-r parsing.txt+pymupdf4llm>=1.28.2diff --git a/requirements/modules/parsing.txt b/requirements/modules/parsing.txtnew file mode 100644index 000000000..fe4421d3c--- /dev/null+++ b/requirements/modules/parsing.txt@@ -0,0 +1,12 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+PyMuPDF>=1.26.0+Pillow>=10.0.0+python-docx>=1.1.0+openpyxl>=3.1.0+python-pptx>=1.0.0+pypdf>=4.0.0+pdfplumber>=0.11.0+reportlab>=4.0.0+defusedxml>=0.7.1+pywin32; sys_platform == 'win32'diff --git a/requirements/modules/partners.txt b/requirements/modules/partners.txtnew file mode 100644index 000000000..bf63c05fd--- /dev/null+++ b/requirements/modules/partners.txt@@ -0,0 +1,20 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+-r memory.txt+qrcode>=7.4.0,<9.0.0+python-telegram-bot[socks]>=22.6,<23.0+wecom-aibot-sdk>=1.0.8,<2.0.0+lark-oapi>=1.5.0,<2.0.0+dingtalk-stream>=0.24.0,<1.0.0+slack-sdk>=3.39.0,<4.0.0+slackify-markdown>=0.2.0,<1.0.0+qq-botpy>=1.2.0,<2.0.0+python-socketio>=5.16.0,<6.0.0+msgpack>=1.1.0,<2.0.0+python-socks[asyncio]>=2.8.0,<3.0.0+socksio>=1.0.0,<2.0.0+websocket-client>=1.9.0,<2.0.0+zulip>=0.8.0,<1.0.0+websockets>=12.0+aiohttp>=3.10.0,<4.0.0+PyJWT[crypto]>=2.8.0,<3.0.0diff --git a/requirements/modules/providers.txt b/requirements/modules/providers.txtnew file mode 100644index 000000000..89eed23d3--- /dev/null+++ b/requirements/modules/providers.txt@@ -0,0 +1,6 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+anthropic>=0.30.0+dashscope>=1.14.0+perplexityai>=0.1.0+oauth-cli-kit>=0.1.1diff --git a/requirements/modules/questions.txt b/requirements/modules/questions.txtnew file mode 100644index 000000000..1007d8fac--- /dev/null+++ b/requirements/modules/questions.txt@@ -0,0 +1,3 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+-r parsing.txtdiff --git a/requirements/modules/reading.txt b/requirements/modules/reading.txtnew file mode 100644index 000000000..e5674e5e2--- /dev/null+++ b/requirements/modules/reading.txt@@ -0,0 +1,7 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+-r knowledge.txt+-r parsing.txt+-r mastery.txt+-r notebook.txt+youtube-transcript-api>=1.2.0,<2.0.0diff --git a/requirements/modules/renderer-manim.txt b/requirements/modules/renderer-manim.txtnew file mode 100644index 000000000..e0014c33d--- /dev/null+++ b/requirements/modules/renderer-manim.txt@@ -0,0 +1,3 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+manim>=0.19.0diff --git a/requirements/modules/research.txt b/requirements/modules/research.txtnew file mode 100644index 000000000..58127883f--- /dev/null+++ b/requirements/modules/research.txt@@ -0,0 +1,3 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+arxiv>=2.0.0diff --git a/requirements/modules/server.txt b/requirements/modules/server.txtnew file mode 100644index 000000000..fd8dd53c9--- /dev/null+++ b/requirements/modules/server.txt@@ -0,0 +1,10 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+fastapi>=0.100.0+uvicorn[standard]>=0.24.0+websockets>=12.0+python-multipart>=0.0.6+bcrypt>=4.0.0+python-jose[cryptography]>=3.3.0+pocketbase>=0.12.0+redis>=5.0.0,<7.0.0diff --git a/requirements/modules/solve.txt b/requirements/modules/solve.txtnew file mode 100644index 000000000..9b2f6702e--- /dev/null+++ b/requirements/modules/solve.txt@@ -0,0 +1,2 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txtdiff --git a/requirements/modules/video-lesson.txt b/requirements/modules/video-lesson.txtnew file mode 100644index 000000000..9b2f6702e--- /dev/null+++ b/requirements/modules/video-lesson.txt@@ -0,0 +1,2 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txtdiff --git a/requirements/modules/visualize.txt b/requirements/modules/visualize.txtnew file mode 100644index 000000000..9b2f6702e--- /dev/null+++ b/requirements/modules/visualize.txt@@ -0,0 +1,2 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txtdiff --git a/requirements/modules/web.txt b/requirements/modules/web.txtnew file mode 100644index 000000000..11cda8313--- /dev/null+++ b/requirements/modules/web.txt@@ -0,0 +1,3 @@+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r ../core.txt+-r server.txtdiff --git a/requirements/server.txt b/requirements/server.txtindex 3e197e1d6..aff8fefa7 100644--- a/requirements/server.txt+++ b/requirements/server.txt@@ -1,40 +1,2 @@-# ============================================-# DeepTutor Server — Full Dependencies (CLI + Web)-# ============================================-# Mirrors pyproject.toml `[project.optional-dependencies].server`.-# Keep in sync with pyproject.toml when adding/updating dependencies.-#-# Public install: pip install deeptutor-# Source install: pip install -e .-# Use this file for Docker/CI when pyproject.toml/source code aren't yet available.---r cli.txt--# --- API server ----fastapi>=0.100.0-uvicorn[standard]>=0.24.0-websockets>=12.0-python-multipart>=0.0.6--# --- Authentication ----bcrypt>=4.0.0-python-jose[cryptography]>=3.3.0--# --- PocketBase (optional sidecar backend) ----# Only used when integrations.pocketbase_url is configured.-pocketbase>=0.12.0--# --- Multi-worker turn coordination ----redis>=5.0.0,<7.0.0--# --- LLM provider runtime (unconditionally imported by provider_core) ----loguru>=0.7.3,<1.0.0-json-repair>=0.57.0,<1.0.0-# Built-in cron service (chat & partner scheduled tasks)-croniter>=6.0.0,<7.0.0-python-dateutil>=2.9.0,<3.0.0--# --- Runtime observability ----# Process-tree memory readings behind /api/system/memory. Imported lazily-# with a /proc fallback, so it is soft rather than required.-psutil>=5.9.0,<8.0.0+# Generated by scripts/sync_module_requirements.py; edit module manifests.+-r modules/server.txtdiff --git a/scripts/build_modules.py b/scripts/build_modules.pynew file mode 100644index 000000000..0fa999fd0--- /dev/null+++ b/scripts/build_modules.py@@ -0,0 +1,139 @@+#!/usr/bin/env python3+"""Build disjoint official wheels from one source revision.++Run with --output dist/modules. Optional --module selects individual wheels;+the default builds core, all modules, and the CLI compatibility metapackage.+This prepares local artifacts only; it never uploads or installs packages.+"""++from __future__ import annotations++import argparse+import json+from pathlib import Path+import shutil+import subprocess+import sys+import tempfile+import tomllib+import zipfile++ROOT = Path(__file__).resolve().parents[1]+sys.path.insert(0, str(ROOT))+from build_support import owner+++def build(output: Path, selected: list[str]) -> list[Path]:+ modules = {+ path.stem: json.loads(path.read_text())+ for path in (ROOT / "deeptutor/modules/manifests").glob("*.json")+ }+ version_ns = {}+ exec((ROOT / "deeptutor/__version__.py").read_text(), version_ns)+ version = version_ns["__version__"]+ project = tomllib.loads((ROOT / "pyproject.toml").read_text())["project"]+ names = selected or [*modules, "cli"]+ output.mkdir(parents=True, exist_ok=True)+ files = [+ path+ for base in ("deeptutor", "deeptutor_cli", "deeptutor_web")+ for path in (ROOT / base).rglob("*")+ if path.is_file()+ and "__pycache__" not in path.parts+ and "tests" not in path.parts+ and path.suffix not in {".pyc", ".pyo"}+ ]+ ownership = {path: owner(path.relative_to(ROOT).as_posix()) for path in files}+ built = []+ for name in names:+ if name not in {*modules, "cli"}:+ raise ValueError(f"Unknown module: {name}")+ with tempfile.TemporaryDirectory(prefix=f"deeptutor-build-{name}-") as directory:+ stage = Path(directory)+ module = modules.get(name)+ package_name = module["distribution"] if module else f"deeptutor-{name}"+ if module:+ for source in files:+ if ownership[source] != name:+ continue+ dest = stage / source.relative_to(ROOT)+ dest.parent.mkdir(parents=True, exist_ok=True)+ shutil.copy2(source, dest)+ dependencies = list(module["requirements"]) if module else []+ if name != "core":+ dependencies += [f"deeptutor=={version}"]+ dependencies += [+ f"{modules[dep]['distribution']}=={version}"+ for dep in (module["requires"] if module else [])+ ]+ config = f"""[build-system]+requires = ["setuptools>=61", "wheel"]+build-backend = "setuptools.build_meta"+[project]+name = {json.dumps(package_name)}+version = {json.dumps(version)}+description = {json.dumps("DeepTutor " + name + " module")}+requires-python = ">=3.11,<3.15"+dependencies = {json.dumps(dependencies)}+[tool.setuptools.packages.find]+where = ["."]+include = ["deeptutor*", "deeptutor_cli*", "deeptutor_web*"]+namespaces = true+[tool.setuptools.package-data]+"deeptutor_web" = ["**/*", ".next/**/*"]+"*" = ["*.json", "*.yaml", "*.yml", "*.md", "*.sh", "*.j2", "*.jinja", "*.ts", "*.tsx", "*.mjs", "*.js", "*.css", "*.html", "*.svg", "*.png", "*.woff2"]+"""+ if name == "core":+ config += '\n[project.scripts]\ndeeptutor = "deeptutor_cli.main:main"\n'+ config += "\n[project.optional-dependencies]\n"+ for key, values in project["optional-dependencies"].items():+ config += f"{json.dumps(key)} = {json.dumps(values)}\n"+ for group, entries in (module or {}).get("entry_points", {}).items():+ config += f"\n[project.entry-points.{json.dumps(group)}]\n"+ for key, value in entries.items():+ config += f"{json.dumps(key)} = {json.dumps(value)}\n"+ (stage / "MANIFEST.in").write_text(+ "recursive-include deeptutor_web *\nrecursive-include deeptutor_web/.next *\n"+ )+ (stage / "pyproject.toml").write_text(config)+ result = subprocess.run(+ [+ sys.executable,+ "-m",+ "pip",+ "wheel",+ "--no-deps",+ "--no-build-isolation",+ "--wheel-dir",+ str(output.resolve()),+ str(stage),+ ],+ text=True,+ capture_output=True,+ )+ if result.returncode:+ raise RuntimeError(result.stdout + result.stderr)+ wheel = output / f"{package_name.replace('-', '_')}-{version}-py3-none-any.whl"+ if not wheel.is_file():+ raise RuntimeError(f"Expected wheel missing: {wheel}")+ built.append(wheel)+ print(wheel.name, flush=True)+ # One installed file has one owner; namespace parents need no duplicate init.+ owners = {}+ for wheel in built:+ with zipfile.ZipFile(wheel) as archive:+ for path in archive.namelist():+ if ".dist-info/" in path or path.endswith("/"):+ continue+ if path in owners:+ raise RuntimeError(f"Wheel overlap: {path} in {owners[path]} and {wheel.name}")+ owners[path] = wheel.name+ return built+++if __name__ == "__main__":+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("--output", type=Path, default=ROOT / "dist/modules")+ parser.add_argument("--module", action="append", default=[])+ args = parser.parse_args()+ build(args.output, args.module)diff --git a/scripts/check_minimal_install.py b/scripts/check_minimal_install.pynew file mode 100644index 000000000..8d1387f97--- /dev/null+++ b/scripts/check_minimal_install.py@@ -0,0 +1,159 @@+#!/usr/bin/env python3+"""Exercise core chat, SQLite persistence and replay with a local model fixture.++Run outside the checkout with an interpreter containing only the core wheel.+--source-core additionally blocks optional source imports for fast development.+No provider credentials or external network calls are used.+"""++import argparse+import asyncio+import importlib.abc+import importlib.machinery+import os+from pathlib import Path+import sys+import tempfile++parser = argparse.ArgumentParser(description=__doc__)+parser.add_argument("--source-core", action="store_true")+parser.add_argument("--capability", default="chat")+parser.add_argument("--home", type=Path)+args = parser.parse_args()+runtime_home = tempfile.TemporaryDirectory(prefix="deeptutor-core-smoke-")+os.environ["DEEPTUTOR_HOME"] = str(args.home) if args.home else runtime_home.name+if args.source_core:+ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))+from deeptutor.modules import catalog++if args.source_core:+ catalog.installed = lambda name: name == "core"++ class BlockOptional(importlib.abc.MetaPathFinder):+ def find_spec(self, fullname, path=None, target=None):+ if fullname.startswith(("deeptutor.", "deeptutor_cli.")):+ relative = fullname.replace(".", "/")+ owner = catalog.module_for_path(relative + ".py")+ if not (Path(__file__).resolve().parents[1] / (relative + ".py")).is_file():+ owner = catalog.module_for_path(relative + "/__init__.py")+ if owner != "core":+ # Wheels retain namespace parents for core-owned shared metadata,+ # without shipping the optional application's __init__.py.+ if any(+ item.startswith(relative + "/")+ for item in catalog.manifests()["core"]["paths"]+ ):+ spec = importlib.machinery.ModuleSpec(+ fullname, loader=None, is_package=True+ )+ spec.submodule_search_locations = [+ str(Path(__file__).resolve().parents[1] / relative)+ ]+ return spec+ raise ModuleNotFoundError(f"Absent module {owner}: {fullname}", name=fullname)++ sys.meta_path.insert(0, BlockOptional())+from deeptutor.app import DeepTutorApp+++async def main():+ app = DeepTutorApp()+ try:+ contracts = {row["name"] for row in app.get_capability_contracts()}+ assert {"chat", "ask_questions", args.capability} <= contracts+ if args.capability == "chat":+ assert contracts == {"chat", "ask_questions"}, contracts+ session, turn = await app.start_turn(+ {"content": "Hello", "capability": args.capability, "tools": []}+ )+ events = [item async for item in app.stream_turn(turn["id"])]+ assert not [event for event in events if event["type"] == "error"], events+ assert any(+ event["type"] == "content" and "minimal core" in event["content"] for event in events+ ), events+ terminal = next(event for event in events if event["type"] == "done")+ assert terminal["metadata"]["status"] == "completed", events+ assert await app.get_session(session["id"]) is not None+ await app.container.close()+ from deeptutor.app.container import set_application_container++ set_application_container(None)+ app = DeepTutorApp()+ replay = [item async for item in app.stream_turn(turn["id"])]+ assert [+ (e["seq"], e["type"], e["content"]) for e in replay if e["seq"] <= terminal["seq"]+ ] == [(e["seq"], e["type"], e["content"]) for e in events if e["seq"] <= terminal["seq"]]+ print("Core chat, durable session and replay: OK")+ finally:+ await app.container.close()+++from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer+import json+import threading+++class Handler(BaseHTTPRequestHandler):+ def log_message(self, *args):+ pass++ def do_POST(self):+ body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))+ self.send_response(200)+ self.send_header(+ "Content-Type", "text/event-stream" if body.get("stream") else "application/json"+ )+ self.end_headers()+ if body.get("stream"):+ for delta, finish in [+ ({"content": "Hello from the minimal core."}, None),+ ({}, "stop"),+ ]:+ value = {+ "id": "smoke",+ "object": "chat.completion.chunk",+ "created": 0,+ "model": "smoke",+ "choices": [{"index": 0, "delta": delta, "finish_reason": finish}],+ }+ self.wfile.write(("data: " + json.dumps(value) + "\n\n").encode())+ self.wfile.write(b"data: [DONE]\n\n")+ else:+ self.wfile.write(+ json.dumps(+ {+ "id": "smoke",+ "object": "chat.completion",+ "created": 0,+ "model": "smoke",+ "choices": [+ {+ "index": 0,+ "message": {+ "role": "assistant",+ "content": "Hello from the minimal core.",+ },+ "finish_reason": "stop",+ }+ ],+ "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2},+ }+ ).encode()+ )+++server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)+threading.Thread(target=server.serve_forever, daemon=True).start()+import deeptutor.services.llm.config as config++config._LLM_CONFIG_CACHE = config.LLMConfig(+ model="smoke",+ api_key="local-test",+ base_url=f"http://127.0.0.1:{server.server_port}/v1",+ wire_api="chat_completions",+)+try:+ asyncio.run(asyncio.wait_for(main(), timeout=30))+finally:+ server.shutdown()+ runtime_home.cleanup()diff --git a/scripts/check_module_install.py b/scripts/check_module_install.pynew file mode 100644index 000000000..a032378c7--- /dev/null+++ b/scripts/check_module_install.py@@ -0,0 +1,141 @@+"""Check real core/Solve wheel installation and data-preserving removal."""++from __future__ import annotations++import argparse+import hashlib+import os+from pathlib import Path+import subprocess+import tempfile+import venv++ROOT = Path(__file__).resolve().parents[1]+++def main():+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("--wheelhouse", required=True, type=Path)+ parser.add_argument(+ "--extended",+ action="store_true",+ help="Also check Parsing, Research and Calendar isolation",+ )+ args = parser.parse_args()+ wheelhouse = args.wheelhouse.resolve()+ with tempfile.TemporaryDirectory(prefix="deeptutor-module-check-") as directory:+ scratch = Path(directory)+ environment = scratch / "venv"+ venv.create(environment, with_pip=True)+ python = environment / ("Scripts/python.exe" if os.name == "nt" else "bin/python")+ home = scratch / "home"+ env = {**os.environ, "DEEPTUTOR_HOME": str(home)}+ env.pop("PYTHONPATH", None)++ def run(*argv):+ subprocess.run([str(python), *map(str, argv)], cwd=scratch, env=env, check=True)++ core = list(wheelhouse.glob("deeptutor-*-py3-none-any.whl"))+ if len(core) != 1:+ raise ValueError("Wheelhouse must contain exactly one core version")+ run("-m", "pip", "install", core[0])++ def module(action, name="solve"):+ run("-m", "deeptutor_cli", "module", action, name, "--wheelhouse", wheelhouse)++ def smoke(capability="chat"):+ run(+ ROOT / "scripts/check_minimal_install.py",+ "--home",+ home,+ "--capability",+ capability,+ )++ smoke()+ run(+ "-c",+ """+from deeptutor.runtime.home import get_runtime_home+from docx import Document+from openpyxl import Workbook, load_workbook+root = get_runtime_home()+document = Document()+document.add_paragraph("Core document creation")+document.save(root / "core.docx")+assert Document(root / "core.docx").paragraphs[0].text == "Core document creation"+workbook = Workbook()+workbook.active["A1"] = "Core spreadsheet creation"+workbook.save(root / "core.xlsx")+assert load_workbook(root / "core.xlsx").active["A1"].value == "Core spreadsheet creation"+""",+ )+ module("install")+ smoke("deep_solve")++ def snapshot():+ return {+ p.relative_to(home): hashlib.sha256(p.read_bytes()).hexdigest()+ for p in home.rglob("*")+ if p.is_file()+ and p.name != "modules.json"+ and p.suffix in {".json", ".sqlite3", ".db", ".docx", ".xlsx"}+ }++ before = snapshot()+ assert before+ module("uninstall")+ assert before == snapshot(), "Uninstall changed application data"+ smoke()+ module("install")+ smoke("deep_solve")+ if args.extended:+ for name in ("parsing", "research", "calendar"):+ module("install", name)+ run(+ "-c",+ """+import asyncio+from datetime import datetime, timedelta, timezone+from deeptutor.modules.catalog import installed+assert not installed("knowledge") and not installed("mastery")+from deeptutor.runtime.home import get_runtime_home+from deeptutor.services.parsing import get_parse_service+source = get_runtime_home() / "isolated-parser.txt"+source.write_text("Parsing independently of knowledge.")+for _ in range(2):+ assert "independently" in get_parse_service().parse(source, engine="text_only").markdown+from deeptutor.agents.research.pipeline import ResearchPipeline+from deeptutor.tools.research_tools import _client+assert _client() is not None+pipeline = ResearchPipeline.__new__(ResearchPipeline)+pipeline.kb_name = None+asyncio.run(pipeline._prepare_pageindex_tools())+from deeptutor.services.calendar import layers+layers.owner_key = lambda: "chat:fixture"+start = datetime.now(timezone.utc)+assert not layers.read_layers("fixture", start, start + timedelta(days=7), "UTC").reviews+""",+ )+ for name in ("research", "calendar", "parsing"):+ preserved = snapshot()+ module("uninstall", name)+ assert preserved == snapshot(), f"Removing {name} changed application data"+ smoke("deep_solve")+ run(+ "-c",+ """+from deeptutor.runtime.home import get_runtime_home+from docx import Document+from openpyxl import load_workbook+root = get_runtime_home()+assert Document(root / "core.docx").paragraphs[0].text == "Core document creation"+assert load_workbook(root / "core.xlsx").active["A1"].value == "Core spreadsheet creation"+""",+ )+ run("-m", "pip", "check")+ print("Core/Solve install, run, replay, uninstall, retained data, reinstall: OK")+++if __name__ == "__main__":+ main()diff --git a/scripts/sync_module_requirements.py b/scripts/sync_module_requirements.pynew file mode 100644index 000000000..2e6bcab1a--- /dev/null+++ b/scripts/sync_module_requirements.py@@ -0,0 +1,57 @@+"""Generate source/Docker dependency files from the same module manifests."""++from __future__ import annotations++import argparse+import json+from pathlib import Path++ROOT = Path(__file__).resolve().parents[1]+++def generated():+ modules = {+ p.stem: json.loads(p.read_text())+ for p in (ROOT / "deeptutor/modules/manifests").glob("*.json")+ }+ header = "# Generated by scripts/sync_module_requirements.py; edit module manifests.\n"+ result = {}+ for name, row in modules.items():+ dependencies = list(row["requirements"])+ prefix = [] if name == "core" else ["-r ../core.txt"]+ if name != "core":+ prefix += [+ f"-r {dependency}.txt" for dependency in row["requires"] if dependency != "core"+ ]+ filename = "core.txt" if name == "core" else f"modules/{name}.txt"+ result[filename] = header + "\n".join(prefix + dependencies) + "\n"+ result["cli.txt"] = header + "-r core.txt\n"+ result["server.txt"] = header + "-r modules/server.txt\n"+ result["full.txt"] = (+ header+ + "\n".join(+ f"-r modules/{name}.txt"+ for name in sorted(modules)+ if name not in {"core", "renderer-manim"} and not name.startswith("parser-")+ )+ + "\n"+ )+ return result+++def main():+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("--check", action="store_true")+ args = parser.parse_args()+ for filename, content in generated().items():+ path = ROOT / "requirements" / filename+ if args.check:+ if not path.exists() or path.read_text() != content:+ raise SystemExit(f"Stale dependency file: {path}")+ else:+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_text(content)+++if __name__ == "__main__":+ main()diff --git a/setup.py b/setup.pynew file mode 100644index 000000000..21f5946db--- /dev/null+++ b/setup.py@@ -0,0 +1,11 @@+"""Use the same ownership filter for ordinary pip/source wheel builds."""++from pathlib import Path+import sys++from setuptools import setup++sys.path.insert(0, str(Path(__file__).resolve().parent))+from build_support import CoreBuildPy++setup(cmdclass={"build_py": CoreBuildPy})diff --git a/tests/agents/video_lesson/test_runtime.py b/tests/agents/video_lesson/test_runtime.pyindex a4f4b46cd..a683c229c 100644--- a/tests/agents/video_lesson/test_runtime.py+++ b/tests/agents/video_lesson/test_runtime.py@@ -51,7 +51,8 @@ def test_video_lesson_available_without_docker(monkeypatch) -> None:from deeptutor.app.facade import DeepTutorAppmonkeypatch.setattr(- "deeptutor.app.facade.shutil.which", lambda name: name if name in {"node", "npm"} else None+ "deeptutor.modules.catalog.shutil.which",+ lambda name: name if name in {"node", "npm"} else None,)app = SimpleNamespace(resolve_capability=lambda value: value)availability = DeepTutorApp.get_capability_availability(app, "video_lesson")diff --git a/tests/api/test_sessions_permanent_delete.py b/tests/api/test_sessions_permanent_delete.pyindex f7322e7ee..ec53b8d68 100644--- a/tests/api/test_sessions_permanent_delete.py+++ b/tests/api/test_sessions_permanent_delete.py@@ -19,9 +19,9 @@ async def test_delete_removes_conversation_descendants_and_messages(tmp_path, moattachments = SimpleNamespace(delete_session=AsyncMock())learning = SimpleNamespace(detach_session=Mock())monkeypatch.setattr(router, "get_attachment_store", lambda: attachments)- monkeypatch.setattr(router, "LearningStore", lambda: learning)+ monkeypatch.setattr("deeptutor.learning.storage.LearningStore", lambda: learning)reading = SimpleNamespace(forget_session=Mock())- monkeypatch.setattr(router, "ReadingCatalogStore", lambda: reading)+ monkeypatch.setattr("deeptutor.reading.catalog_store.ReadingCatalogStore", lambda: reading)turns = SimpleNamespace(cancel_turn_and_wait=AsyncMock(return_value=True))monkeypatch.setattr(router, "_turn_application_service", lambda: turns)monkeypatch.setattr(diff --git a/tests/api/test_subagents_router.py b/tests/api/test_subagents_router.pyindex 29fc8e1ed..6503ebc07 100644--- a/tests/api/test_subagents_router.py+++ b/tests/api/test_subagents_router.py@@ -70,7 +70,7 @@ def client(monkeypatch, tmp_path):"list_backend_kinds",lambda: ["claude_code", "codex", "grok", "hermes_remote", "partner"],)- monkeypatch.setattr(subagents_module, "assert_path_allowed", lambda p: Path(p))+ monkeypatch.setattr("deeptutor.services.rag.linked_kb.assert_path_allowed", lambda p: Path(p))# Isolate settings persistence to a temp file — the PUT path otherwise# writes the developer's real data/user/settings/subagent.json.monkeypatch.setattr(diff --git a/tests/api/test_unified_ws_turn_runtime.py b/tests/api/test_unified_ws_turn_runtime.pyindex 508b142f1..051b47f6c 100644--- a/tests/api/test_unified_ws_turn_runtime.py+++ b/tests/api/test_unified_ws_turn_runtime.py@@ -25,8 +25,12 @@ def _fake_skill_service() -> SimpleNamespace:@pytest.fixture(autouse=True)def _isolate_runtime_services(monkeypatch, tmp_path):+ from deeptutor.services.path_service import PathServicefrom deeptutor.services.task_board import TaskBoardStore+ paths = PathService(workspace_root=tmp_path / "data")+ monkeypatch.setattr("deeptutor.services.workspace.service.get_path_service", lambda: paths)+board = TaskBoardStore(tmp_path / "tasks.sqlite")monkeypatch.setattr("deeptutor.services.task_board.get_task_board_store", lambda **_kwargs: boarddiff --git a/tests/app/test_capability_contracts.py b/tests/app/test_capability_contracts.pyindex 9c1dc0826..96a4ea406 100644--- a/tests/app/test_capability_contracts.py+++ b/tests/app/test_capability_contracts.py@@ -24,14 +24,19 @@ def test_single_capability_contract_serializes_availability() -> None:def test_capability_list_preserves_optional_install_hint(monkeypatch: pytest.MonkeyPatch, manim_available: bool) -> None:- original_find_spec = importlib.util.find_spec+ from deeptutor.modules import catalog- def find_spec(name: str, package: str | None = None) -> object | None:- if name == "manim":- return object() if manim_available else None- return original_find_spec(name, package)+ original_statuses = catalog.module_statuses- monkeypatch.setattr(importlib.util, "find_spec", find_spec)+ def statuses():+ rows = original_statuses()+ for row in rows:+ if row["id"] == "renderer-manim":+ row["ready"] = manim_available+ row["issues"] = [] if manim_available else ["Install renderer-manim dependencies"]+ return rows++ monkeypatch.setattr(catalog, "module_statuses", statuses)contracts = DeepTutorApp().get_capability_contracts()by_name = {contract["name"]: contract for contract in json.loads(json.dumps(contracts))}@@ -42,4 +47,4 @@ def test_capability_list_preserves_optional_install_hint(if manim_available:assert availability["install_hint"] == ""else:- assert "math-animator" in availability["install_hint"]+ assert "renderer-manim" in availability["install_hint"]diff --git a/tests/app/test_waiting_turn_recovery.py b/tests/app/test_waiting_turn_recovery.pyindex 33379c4a7..af45233d2 100644--- a/tests/app/test_waiting_turn_recovery.py+++ b/tests/app/test_waiting_turn_recovery.py@@ -78,6 +78,12 @@ def _workspace_root(tmp_path, monkeypatch: pytest.MonkeyPatch):"""root = tmp_path / "workspace"root.mkdir()+ from deeptutor.services.path_service import PathService++ # General/unbound sessions use the workspace catalog, not the legacy+ # deployment-folder selector. Isolate that catalog as well.+ paths = PathService(workspace_root=tmp_path / "data")+ monkeypatch.setattr("deeptutor.services.workspace.service.get_path_service", lambda: paths)monkeypatch.setenv("DEEPTUTOR_WORKSPACE_ROOT", str(root))monkeypatch.delenv("DEEPTUTOR_WORKSPACE_ALLOWED_ROOTS", raising=False)diff --git a/tests/capabilities/test_loop_registry.py b/tests/capabilities/test_loop_registry.pyindex f96e1e3c3..b07fbb036 100644--- a/tests/capabilities/test_loop_registry.py+++ b/tests/capabilities/test_loop_registry.py@@ -220,6 +220,9 @@ def test_duplicate_external_name_first_wins(monkeypatch) -> None:def test_active_loop_capabilities_includes_external(monkeypatch) -> None:from deeptutor.capabilities import registry+ # External activation is independent of the install's first-run setup gaps.+ monkeypatch.setattr("deeptutor.capabilities.setup.binding.setup_gaps", lambda: ())+def fake_entry_points(*, group: str):return [_ep("demo_loop", lambda: _DemoLoop)]diff --git a/tests/modules/test_isolated_features.py b/tests/modules/test_isolated_features.pynew file mode 100644index 000000000..b3d4f0159--- /dev/null+++ b/tests/modules/test_isolated_features.py@@ -0,0 +1,149 @@+"""Run independent feature paths with unrelated module imports prohibited.++A full developer environment hides missing wheel dependencies. Each subprocess+has a fresh import table and fails even when the excluded source files exist.+"""++import os+from pathlib import Path+import subprocess+import sys+import textwrap++import pytest++ROOT = Path(__file__).resolve().parents[2]+BOOTSTRAP = """+import asyncio, importlib.abc, importlib.machinery, sys+from pathlib import Path+from deeptutor.modules import catalog+allowed = set(catalog.dependency_order([FEATURE])) | {"core"}+catalog.installed = lambda name: name in allowed+catalog.selection = lambda: {}+root = Path.cwd()+class Isolate(importlib.abc.MetaPathFinder):+ def find_spec(self, fullname, path=None, target=None):+ if not fullname.startswith(("deeptutor.", "deeptutor_cli.")):+ return+ relative = fullname.replace(".", "/")+ candidate = relative + ".py"+ if not (root / candidate).is_file():+ candidate = relative + "/__init__.py"+ owner = catalog.module_for_path(candidate)+ if owner in allowed:+ return+ if any(prefix.startswith(relative + "/") for name in allowed+ for prefix in catalog.manifests()[name]["paths"]):+ spec = importlib.machinery.ModuleSpec(fullname, loader=None, is_package=True)+ spec.submodule_search_locations = [str(root / relative)]+ return spec+ raise ModuleNotFoundError(f"Undeclared dependency: {FEATURE} -> {owner}: {fullname}")+sys.meta_path.insert(0, Isolate())+from deeptutor.services.setup import init_user_directories+init_user_directories()+"""+ASSEMBLY = """+from importlib import import_module+for owner in sorted(allowed):+ row = catalog.manifests()[owner]+ for kind in ("capabilities", "loops", "tools"):+ for name, spec in row[kind].items():+ if catalog.contribution_enabled(kind, name):+ module, attribute = spec["class_path"].split(":")+ assert getattr(import_module(module), attribute)() is not None+ for service in row["services"]:+ for action in ("start", "stop"):+ module, attribute = service[action].split(":")+ assert callable(getattr(import_module(module), attribute))+ for command in row["commands"]:+ module, attribute = command["register"].split(":")+ assert callable(getattr(import_module(module), attribute))+"""+CASES = {+ "core": """+from deeptutor.services.suggestions import _collect_material+assert not _collect_material(5)+from deeptutor.services.doctor import run_diagnostics+report = asyncio.run(run_diagnostics())+assert next(row for row in report.checks if row.key == "rag").status == "skip"+from deeptutor.runtime.registry.tool_registry import ToolRegistry+registry = ToolRegistry(); registry.load_builtins()+assert registry.get("paper_search") is None+assert registry.get("partner_read") is None+assert registry.get("web_search") is not None+""",+ "parsing": """+from deeptutor.services.parsing import get_parse_service+from deeptutor.runtime.home import get_runtime_home+source = get_runtime_home() / "lesson.txt"+source.write_text("Independent parsing still works.")+service = get_parse_service()+first = service.parse(source, engine="text_only")+second = service.parse(source, engine="text_only")+assert "Independent parsing" in first.markdown+assert first.markdown == second.markdown+""",+ "research": """+from deeptutor.agents.research.pipeline import ResearchPipeline+from deeptutor.tools.research_tools import _client+assert _client() is not None+pipeline = ResearchPipeline.__new__(ResearchPipeline)+pipeline.kb_name = None+asyncio.run(pipeline._prepare_pageindex_tools())+assert pipeline._pageindex_tool_context is None+from deeptutor.runtime.registry.tool_registry import ToolRegistry+registry = ToolRegistry(); registry.load_builtins()+assert registry.get("paper_search") is not None+assert registry.get("knowledge_frontier") is None+""",+ "questions": """+from deeptutor.agents.question.pipeline import QuestionPipeline+pipeline = QuestionPipeline.__new__(QuestionPipeline)+pipeline.kb_name = None+asyncio.run(pipeline._prepare_pageindex_tools())+assert pipeline._pageindex_tool_context is None+""",+ "calendar": """+from datetime import datetime, timezone, timedelta+from deeptutor.services.calendar import layers+from deeptutor.services.cron import service+from types import SimpleNamespace+service.get_cron_service = lambda: SimpleNamespace(list_jobs=lambda owner: [])+layers.owner_key = lambda: "fixture"+start = datetime.now(timezone.utc)+result = layers.read_layers("fixture", start, start + timedelta(days=7), "UTC")+assert not result.automations+assert not result.reviews+""",+ "server": """+from fastapi.testclient import TestClient+from deeptutor.api.main import app+with TestClient(app) as client:+ for path in ("/", "/api/modules", "/api/sessions", "/api/settings/readiness", "/api/dashboard/learning-index"):+ response = client.get(path)+ assert response.status_code == 200, (path, response.status_code, response.text)+ assert client.get("/api/settings/document-parsing").status_code == 404+""",+}+++ "feature", sorted(path.stem for path in (ROOT / "deeptutor/modules/manifests").glob("*.json"))+)+def test_feature_without_unrelated_modules(feature, tmp_path):+ result = subprocess.run(+ [+ sys.executable,+ "-c",+ f"FEATURE = {feature!r}\n"+ + BOOTSTRAP+ + ASSEMBLY+ + textwrap.dedent(CASES.get(feature, "")),+ ],+ cwd=ROOT,+ env={**os.environ, "DEEPTUTOR_HOME": str(tmp_path)},+ text=True,+ capture_output=True,+ timeout=45,+ )+ assert result.returncode == 0, result.stdout + result.stderrdiff --git a/tests/modules/test_modules.py b/tests/modules/test_modules.pynew file mode 100644index 000000000..c05a239e8--- /dev/null+++ b/tests/modules/test_modules.py@@ -0,0 +1,263 @@+"""Module boundaries, lifecycle safety and per-turn extension ownership."""++from __future__ import annotations++import asyncio+from dataclasses import dataclass+import json+from pathlib import Path+import subprocess+import sys++import pytest++from deeptutor.modules import catalog, lifecycle++[email protected](autouse=True)+def isolated_state(tmp_path, monkeypatch):+ monkeypatch.setattr(catalog, "state_path", lambda: tmp_path / "modules.json")+ monkeypatch.setattr(lifecycle, "state_path", lambda: tmp_path / "modules.json")+++def test_dependent_disable_requires_explicit_order():+ assert "reading" in lifecycle.plan("disable", "knowledge")["blocked_by"]+ with pytest.raises(lifecycle.ModuleLifecycleError, match="Required by"):+ lifecycle.change("disable", "knowledge")+ assert not catalog.state_path().exists()+++def test_disable_enable_preserves_files_and_assembles_consistently(tmp_path):+ from deeptutor.capabilities.registry import all_loop_capabilities+ from deeptutor.runtime.registry.capability_registry import CapabilityRegistry+ from deeptutor.runtime.request_contracts import CAPABILITY_CONFIG_MODELS++ data = tmp_path / "user-content.json"+ data.write_text('{"preserve": true}')+ lifecycle.change("disable", "solve")+ assert not catalog.module_enabled("solve")+ registry = CapabilityRegistry()+ registry.load_builtins()+ assert "deep_solve" not in {row["name"] for row in registry.get_manifests()}+ assert "deep_solve" not in CAPABILITY_CONFIG_MODELS+ assert "solve" not in {extension.name for extension in all_loop_capabilities()}+ lifecycle.change("enable", "solve")+ assert catalog.module_enabled("solve")+ assert json.loads(data.read_text()) == {"preserve": True}+++def test_environment_cannot_change_while_runtime_holds_lease():+ with lifecycle.environment_lease():+ with pytest.raises(lifecycle.ModuleLifecycleError, match="in use"):+ lifecycle.change("disable", "solve")+ lifecycle.change("disable", "solve")+++def test_environment_lock_crosses_process_boundaries():+ command = [+ sys.executable,+ "-c",+ "from deeptutor.modules.lifecycle import environment_lease; "+ "lease=environment_lease(exclusive=True); lease.__enter__()",+ ]+ with lifecycle.environment_lease():+ result = subprocess.run(command, text=True, capture_output=True)+ assert result.returncode != 0+ assert "Environment is in use" in result.stderr+ assert subprocess.run(command, capture_output=True).returncode == 0+++def test_invalid_state_is_preserved_and_fails_closed():+ catalog.state_path().write_text('{"schema_version":1,"enabled":{"solve":"yes"}}')+ with pytest.raises(ValueError, match="Invalid module selection"):+ lifecycle.change("enable", "solve")+ assert '"yes"' in catalog.state_path().read_text()+++def test_core_cannot_be_removed():+ for action in ("disable", "uninstall"):+ with pytest.raises(lifecycle.ModuleLifecycleError, match="core module"):+ lifecycle.plan(action, "core")+++def test_core_does_not_offer_tools_owned_by_missing_features(monkeypatch):+ from deeptutor.runtime.registry.tool_registry import ToolRegistry++ monkeypatch.setattr(catalog, "installed", lambda name: name == "core")+ registry = ToolRegistry()+ registry.load_builtins()+ for name in ("paper_search", "partner_read", "partner_memorize", "partner_search"):+ assert registry.get(name) is None+ assert registry.get("web_search") is not None+ assert "memory" in catalog.dependency_order(["partners"])+++def test_source_install_has_no_pip_side_effect(monkeypatch):+ monkeypatch.setattr(lifecycle, "_pip", lambda argv: pytest.fail("pip was invoked"))+ with pytest.raises(lifecycle.ModuleLifecycleError, match="source checkout"):+ lifecycle.change("install", "solve")+++def test_per_turn_factory_once_and_state_isolation(monkeypatch):+ from deeptutor.capabilities import registry+ from deeptutor.core.context import UnifiedContext++ calls = []++ @dataclass+ class Extension:+ name: str = "test_extension"+ owned_tools: tuple = ()++ def is_active(self, context):+ return context.user_message == "activate"++ def factory():+ calls.append(1)+ return Extension()++ monkeypatch.setattr(registry, "BUILTIN_LOOP_CAPABILITY_SPECS", ())+ monkeypatch.setattr(+ registry, "discover_external_loop_capabilities", lambda: (("test_extension", factory),)+ )+ first = UnifiedContext(user_message="idle")+ assert not registry.active_loop_capabilities(first)+ first.user_message = "activate"+ active = registry.active_loop_capabilities(first)[0]+ assert registry.active_loop_capabilities(first)[0] is active+ second = UnifiedContext(user_message="activate")+ assert registry.active_loop_capabilities(second)[0] is not active+ assert len(calls) == 2+++def test_manifest_dependency_order_and_path_ownership():+ from build_support import owner++ rows = catalog.manifests()+ for name, row in rows.items():+ order = catalog.dependency_order([name])+ assert order[-1] == name+ for prefix in row["paths"]:+ assert owner(prefix) == catalog.module_for_path(prefix) == name+ for kind in ("capabilities", "loops"):+ for spec in row[kind].values():+ relative = spec["class_path"].split(":")[0].replace(".", "/") + ".py"+ assert catalog.module_for_path(relative) == name+++def test_service_callbacks_remain_paired_for_partial_startup():+ from deeptutor.modules.services import module_service_callbacks++ starts = module_service_callbacks("start", None)+ stops = module_service_callbacks("stop", None)+ assert len(starts) == len(stops)+ for start, stop in zip(starts, stops):+ assert start.args[0].replace(":start_", ":stop_") == stop.args[0]++[email protected]("failure_stage", ["install", "selection"])+def test_failed_install_rolls_back_new_packages_without_touching_selection(+ monkeypatch, failure_stage+):+ from types import SimpleNamespace++ from deeptutor.__version__ import __version__++ monkeypatch.setattr(lifecycle, "source_checkout", lambda: False)+ packages = [SimpleNamespace(metadata={"Name": "deeptutor"}, version=__version__)]+ monkeypatch.setattr(lifecycle.metadata, "distributions", lambda: list(packages))+ calls = []++ def pip(argv):+ calls.append(argv)+ if "--report" in argv:+ Path(argv[argv.index("--report") + 1]).write_text(+ json.dumps(+ {+ "install": [+ {+ "metadata": {"name": "deeptutor-solve", "version": __version__},+ "download_info": {"url": "file:///fixture.whl"},+ }+ ]+ }+ )+ )+ elif "wheel" in argv:+ (Path(argv[argv.index("--wheel-dir") + 1]) / "fixture.whl").touch()+ elif "install" in argv:+ packages.append(+ SimpleNamespace(metadata={"Name": "deeptutor-solve"}, version=__version__)+ )+ if failure_stage == "install":+ raise lifecycle.ModuleLifecycleError("fixture install failed")+ elif "uninstall" in argv:+ assert argv[-1] == "deeptutor-solve"+ packages.pop()+ return ""++ monkeypatch.setattr(lifecycle, "_pip", pip)+ if failure_stage == "selection":++ def reject_selection(_enabled):+ raise lifecycle.ModuleLifecycleError("fixture selection failed")++ monkeypatch.setattr(lifecycle, "_save_selection", reject_selection)+ with pytest.raises(lifecycle.ModuleLifecycleError, match=f"fixture {failure_stage} failed"):+ lifecycle.change("install", "solve")+ assert len(packages) == 1+ assert not catalog.state_path().exists()+ assert "uninstall" in calls[-1]++[email protected]("action", ["install", "uninstall"])+def test_invalid_state_never_modifies_packages(action, monkeypatch):+ catalog.state_path().write_text('{"schema_version":1,"enabled":{"solve":"invalid"}}')+ monkeypatch.setattr(lifecycle, "source_checkout", lambda: False)+ monkeypatch.setattr(lifecycle, "_pip", lambda _argv: pytest.fail("pip mutated invalid state"))+ with pytest.raises(ValueError, match="Invalid module selection"):+ lifecycle.change(action, "solve")+++def test_shared_home_is_locked_across_python_environments(tmp_path, monkeypatch):+ with lifecycle.environment_lease():+ monkeypatch.setattr(sys, "prefix", str(tmp_path / "different-environment"))+ with pytest.raises(lifecycle.ModuleLifecycleError, match="in use"):+ with lifecycle.environment_lease(exclusive=True):+ pytest.fail("Another interpreter changed a live deployment")+++def test_enable_rejects_version_mismatch(monkeypatch):+ monkeypatch.setattr(lifecycle, "source_checkout", lambda: False)+ monkeypatch.setattr(lifecycle, "installed", lambda _name: True)+ monkeypatch.setattr(lifecycle.metadata, "version", lambda _name: "0.0.0")+ with pytest.raises(lifecycle.ModuleLifecycleError, match="must match core"):+ lifecycle.change("enable", "solve")+ assert not catalog.state_path().exists()+++def test_optional_tool_requires_both_owners(monkeypatch):+ present = {"core", "research"}+ monkeypatch.setattr(catalog, "installed", lambda name: name in present)+ assert not catalog.contribution_enabled("tools", "knowledge_frontier")+ present.update(catalog.dependency_order(["knowledge"]))+ assert catalog.contribution_enabled("tools", "knowledge_frontier")+ present.remove("research")+ assert not catalog.contribution_enabled("tools", "knowledge_frontier")+++def test_uninstall_checks_external_distribution_dependents(monkeypatch):+ from types import SimpleNamespace++ monkeypatch.setattr(lifecycle, "source_checkout", lambda: False)+ monkeypatch.setattr(lifecycle, "dependents", lambda *a, **kw: [])+ monkeypatch.setattr(+ lifecycle.metadata,+ "distributions",+ lambda: [+ SimpleNamespace(+ metadata={"Name": "third-party-tutor"}, requires=["deeptutor-solve>=1.0"]+ )+ ],+ )+ assert lifecycle.plan("uninstall", "solve")["blocked_by"] == ["third-party-tutor"]diff --git a/tests/modules/test_render_cancellation.py b/tests/modules/test_render_cancellation.pynew file mode 100644index 000000000..700a6dd6e--- /dev/null+++ b/tests/modules/test_render_cancellation.py@@ -0,0 +1,55 @@+"""Cancellation cleans up a real render subprocess without requiring Manim."""++import asyncio+import subprocess+import sys+from types import SimpleNamespace++import pytest++[email protected]("returncode", [0, 128])+def test_windows_cleanup_targets_the_entire_owned_tree(monkeypatch, returncode):+ from deeptutor.runtime import process++ calls = []+ monkeypatch.setattr(process, "os", SimpleNamespace(name="nt"))++ def run(argv, **kwargs):+ calls.append((argv, kwargs))+ return SimpleNamespace(returncode=returncode)++ monkeypatch.setattr(process.subprocess, "run", run)+ process.kill_process_tree(12345)+ assert calls[0][0] == ["taskkill", "/PID", "12345", "/T", "/F"]+ assert calls[0][1]["timeout"] == 10+++async def test_cancel_reaps_render_process(tmp_path, monkeypatch):+ from deeptutor.agents.math_animator import renderer++ real_popen = subprocess.Popen+ processes = []++ def spawn(_argv, **kwargs):+ process = real_popen([sys.executable, "-c", "import time; time.sleep(60)"], **kwargs)+ processes.append(process)+ return process++ monkeypatch.setattr(renderer.subprocess, "Popen", spawn)+ service = renderer.ManimRenderService("cancel", output_dir=tmp_path, workspace_root=tmp_path)+ source = tmp_path / "scene.py"+ source.write_text("class Fixture(Scene): pass")+ task = asyncio.create_task(+ service._run_manim(+ code_path=source, scene_name="Fixture", quality="low", save_last_frame=False+ )+ )+ async with asyncio.timeout(3):+ while not processes:+ await asyncio.sleep(0.01)+ task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await asyncio.wait_for(task, 3)+ assert processes[0].poll() is not Nonediff --git a/tests/modules/test_worker_stream.py b/tests/modules/test_worker_stream.pynew file mode 100644index 000000000..1f42efb7b--- /dev/null+++ b/tests/modules/test_worker_stream.py@@ -0,0 +1,91 @@+"""A real worker must yield before exit and be reaped when the turn stops."""++import asyncio+import os+from pathlib import Path+import sys++import pytest++from deeptutor.plugins.runtime import _WorkerClient+++def worker(tmp_path, source):+ package = tmp_path / "fixture_worker"+ package.mkdir()+ (package / "__init__.py").write_text("")+ (package / "entry.py").write_text(source)+ return _WorkerClient(+ python_path=Path(sys.executable),+ venv_path=tmp_path,+ module="fixture_worker.entry",+ permissions={},+ )+++async def test_events_are_live_and_cancel_reaps_worker(tmp_path):+ client = worker(+ tmp_path,+ """import json,os,sys,time+json.loads(sys.stdin.read())+print(json.dumps({"kind":"event","event":{"type":"content","content":str(os.getpid())}}),flush=True)+time.sleep(60)+""",+ )+ stream = client.stream("run_capability", {})+ event = await asyncio.wait_for(anext(stream), timeout=5)+ pid = int(event["content"])+ os.kill(pid, 0)+ await asyncio.wait_for(stream.aclose(), timeout=5)+ with pytest.raises(ProcessLookupError):+ os.kill(pid, 0)+++async def test_complete_stream_and_guard_rechecked(tmp_path):+ client = worker(+ tmp_path,+ """import json,sys+json.loads(sys.stdin.read())+print(json.dumps({"kind":"event","event":{"type":"content","content":"hello"}}),flush=True)+print(json.dumps({"kind":"complete"}),flush=True)+""",+ )+ checked = []+ client.guard = lambda: checked.append(True)+ assert [row["content"] async for row in client.stream("run_capability", {})] == ["hello"]+ assert len(checked) == 3++[email protected]("output", ["{}", '{"kind":"event","event":{}}', '{"kind":"complete"}\n{}'])+async def test_malformed_or_truncated_stream_fails(tmp_path, output):+ client = worker(tmp_path, f"import sys\nsys.stdin.read()\nprint({output!r},flush=True)\n")+ with pytest.raises(ExceptionGroup):+ async for _ in client.stream("run_capability", {}):+ pass+++async def test_legacy_buffered_worker_cancellation_reaps_process(tmp_path):+ ready = tmp_path / "pid"+ client = worker(+ tmp_path,+ f"""import json,os,sys,time+from pathlib import Path+json.loads(sys.stdin.read())+Path({str(ready)!r}).write_text(str(os.getpid()))+time.sleep(60)+""",+ )+ task = asyncio.create_task(client.request_async("run_capability", {}))+ async with asyncio.timeout(5):+ while not ready.exists():+ await asyncio.sleep(0.01)+ pid = int(ready.read_text())+ task.cancel()+ with pytest.raises(asyncio.CancelledError):+ await asyncio.wait_for(task, 5)+ with pytest.raises(ProcessLookupError):+ os.kill(pid, 0)diff --git a/tests/multi_user/test_kb_move.py b/tests/multi_user/test_kb_move.pyindex 9e20115dc..23cadf11e 100644--- a/tests/multi_user/test_kb_move.py+++ b/tests/multi_user/test_kb_move.py@@ -146,7 +146,7 @@ def test_failed_publish_restores_source_destination_and_assignment(as_user, monkdef test_legacy_account_selection_redirect_is_private_to_owner(as_user):- from fastapi import HTTPException+ from deeptutor.core.errors import AccessErrorwith as_user("alice"):_make_kb("atlas", b"source")@@ -154,7 +154,7 @@ def test_legacy_account_selection_redirect_is_private_to_owner(as_user):move_kb(qualified_kb_id("atlas"), destination)assert resolve_kb("user:kb:atlas").id == qualified_kb_id("atlas", destination)with as_user("bob"):- with pytest.raises(HTTPException):+ with pytest.raises(AccessError):resolve_kb("user:kb:atlas")diff --git a/tests/multi_user/test_partner_access.py b/tests/multi_user/test_partner_access.pyindex 0a82c1c34..6b15982a7 100644--- a/tests/multi_user/test_partner_access.py+++ b/tests/multi_user/test_partner_access.py@@ -5,6 +5,7 @@ from __future__ import annotationsfrom fastapi import HTTPExceptionimport pytest+from deeptutor.core.errors import AccessErrorfrom deeptutor.multi_user import partner_accessfrom deeptutor.multi_user.grants import empty_grant, normalize_grant@@ -82,7 +83,7 @@ def test_non_admin_allowed_only_for_assigned(as_user, monkeypatch):)with as_user("u_alice", role="user"):partner_access.assert_partner_allowed("p1") # assigned → ok- with pytest.raises(HTTPException) as exc:+ with pytest.raises(AccessError) as exc:partner_access.assert_partner_allowed("p2")assert exc.value.status_code == 403@@ -143,7 +144,7 @@ def test_a_partner_someone_else_owns_is_not_manageable(as_user, monkeypatch):monkeypatch.setattr(partner_access, "load_grant", lambda uid: empty_grant(uid))with as_user("u_alice", role="user"):assert not partner_access.can_manage_partner("p1")- with pytest.raises(HTTPException) as exc:+ with pytest.raises(AccessError) as exc:partner_access.assert_partner_manageable("p1")assert exc.value.status_code == 403diff --git a/tests/multi_user/test_skill_resolution_scoped.py b/tests/multi_user/test_skill_resolution_scoped.pyindex fae49854f..ce5cc5fe9 100644--- a/tests/multi_user/test_skill_resolution_scoped.py+++ b/tests/multi_user/test_skill_resolution_scoped.py@@ -5,6 +5,7 @@ from __future__ import annotationsfrom fastapi import HTTPExceptionimport pytest+from deeptutor.core.errors import AccessErrorfrom deeptutor.multi_user import grants as grants_modfrom deeptutor.multi_user.skill_access import (assert_skill_allowed,@@ -57,7 +58,7 @@ def test_assigned_skill_loads_admin_skill_body(mu_isolated_root, as_user):def test_unassigned_skill_rejected(mu_isolated_root, as_user):with as_user("u_bob", role="user"):- with pytest.raises(HTTPException) as exc:+ with pytest.raises(AccessError) as exc:assert_skill_allowed("forbidden-skill")assert exc.value.status_code == 403diff --git a/tests/multi_user/test_workspace_resources.py b/tests/multi_user/test_workspace_resources.pyindex 07dd90c64..b34e67868 100644--- a/tests/multi_user/test_workspace_resources.py+++ b/tests/multi_user/test_workspace_resources.py@@ -5,6 +5,7 @@ from pathlib import Pathfrom fastapi import HTTPExceptionimport pytest+from deeptutor.core.errors import AccessErrorfrom deeptutor.multi_user.knowledge_access import (current_kb_manager,list_visible_knowledge_bases,@@ -78,21 +79,21 @@ def test_knowledge_origins_selection_and_grants(as_user):assert [r["id"] for r in list_visible_knowledge_bases()] == [local_id]assert resolve_kb("same").base_dir == legacy_rootassert resolve_kb(local_id).base_dir == legacy_root- with pytest.raises(HTTPException, match="403"):+ with pytest.raises(AccessError, match="not assigned"):resolve_kb(global_id)- with pytest.raises(HTTPException):+ with pytest.raises(AccessError):resolve_kb("admin:kb:same")service.update_workspace(b["workspace_id"], resources={"knowledge_bases": [global_id, local_id]})with workspace_context(b["workspace_id"]):- with pytest.raises(HTTPException):+ with pytest.raises(AccessError):resolve_kb("same")assert resolve_kb(global_id).base_dir != resolve_kb(local_id).base_dirservice.update_workspace(b["workspace_id"], resources={"knowledge_bases": []})with workspace_context(b["workspace_id"]):assert list_visible_knowledge_bases() == []- with pytest.raises(HTTPException):+ with pytest.raises(AccessError):resolve_kb(local_id)token = library_request.set(True)try:@@ -101,7 +102,7 @@ def test_knowledge_origins_selection_and_grants(as_user):finally:library_request.reset(token)with as_user("bob"):- with pytest.raises(HTTPException):+ with pytest.raises(AccessError):resolve_kb(local_id)with pytest.raises(WorkspaceError):ContentWorkspaceService().create_workspace(@@ -129,7 +130,7 @@ def test_inherited_workspace_keeps_account_subagents_without_sharing_kbs(as_user)with workspace_context(workspace["workspace_id"]):assert list_visible_knowledge_bases() == []- with pytest.raises(HTTPException):+ with pytest.raises(AccessError):resolve_kb("account:kb:my-agent")@@ -147,17 +148,17 @@ def test_explicit_learning_sources_allow_reads_without_changing_workspace_or_wri"workspace_id"]with workspace_context(target):- with pytest.raises(HTTPException):+ with pytest.raises(AccessError):resolve_kb(source)with learning_source_access([source]):assert resolve_kb(source).name == "notes"assert current_workspace_id() == target- with pytest.raises(HTTPException):+ with pytest.raises(AccessError):resolve_kb(source, require_write=True)- with pytest.raises(HTTPException):+ with pytest.raises(AccessError):resolve_kb(source)with as_user("bob"), learning_source_access([f"workspace:{target}:kb:notes"]):- with pytest.raises(HTTPException):+ with pytest.raises(AccessError):resolve_kb(f"workspace:{target}:kb:notes")diff --git a/tests/services/parsing/test_engines.py b/tests/services/parsing/test_engines.pyindex 84d6edfe5..182626f45 100644--- a/tests/services/parsing/test_engines.py+++ b/tests/services/parsing/test_engines.py@@ -960,27 +960,16 @@ def test_install_manager_spec_allowlist() -> None:assert "mineru" not in ENGINE_PIP_SPECS-def test_install_manager_upgrades_existing_package(monkeypatch) -> None:+def test_install_manager_requires_offline_module_change(monkeypatch) -> None:from deeptutor.services.parsing.engines import _installmanager = _install.BackgroundJobManager()- captured: dict = {}-- def fake_launch(**kwargs):- captured.update(kwargs)- return {"ok": True, "message": ""}-- monkeypatch.setattr(manager, "_launch", fake_launch)- manager.start_install(engine="docling", specs=_install.ENGINE_PIP_SPECS["docling"])-- assert captured["cmd"][:6] == [- _install.sys.executable,- "-m",- "pip",- "install",- "--upgrade",- "--no-input",- ]+ monkeypatch.setattr(+ manager, "_launch", lambda **kwargs: pytest.fail("mutated live environment")+ )+ result = manager.start_install(engine="docling", specs=_install.ENGINE_PIP_SPECS["docling"])+ assert result["ok"] is False+ assert "deeptutor module install parser-docling" in result["message"]def test_model_download_allowlist() -> None:diff --git a/tests/services/parsing/test_mineru_process_lifecycle.py b/tests/services/parsing/test_mineru_process_lifecycle.pyindex a53ce9e2f..5f8b9e764 100644--- a/tests/services/parsing/test_mineru_process_lifecycle.py+++ b/tests/services/parsing/test_mineru_process_lifecycle.py@@ -9,7 +9,7 @@ from types import SimpleNamespaceimport psutilimport pytest-from deeptutor.knowledge import indexing_run+from deeptutor.services.parsing import progressfrom deeptutor.services.parsing.engines.mineru import local@@ -23,9 +23,7 @@ def run_fixture(tmp_path, monkeypatch, code, run=None, idle=0.05, timeout=30, exreturn popen([sys.executable, "-c", code, output], **kwargs)monkeypatch.setattr(local.subprocess, "Popen", spawn)- monkeypatch.setattr(- indexing_run, "current_run", lambda: run or SimpleNamespace(check=lambda: None)- )+ monkeypatch.setattr(progress, "current_run", lambda: run or SimpleNamespace(check=lambda: None))monkeypatch.setattr(local, "_LOCAL_PARSE_IDLE_TIMEOUT_SECONDS", idle)monkeypatch.setattr(local, "_LOCAL_PARSE_TIMEOUT_SECONDS", timeout)monkeypatch.delenv("MINERU_TASK_RESULT_TIMEOUT_SECONDS", raising=False)@@ -100,7 +98,7 @@ def test_deadline_and_cancellation_settle_the_owned_tree(tmp_path, monkeypatch,def check():if cancelled and list((tmp_path / "out").glob(".mineru-attempt-*/output/child.pid")):- raise indexing_run.IndexingCancelled("controlled cancellation")+ raise progress.IndexingCancelled("controlled cancellation")result, elapsed = run_fixture(tmp_path,diff --git a/tests/services/session/test_attachment_parsing.py b/tests/services/session/test_attachment_parsing.pyindex 097d00065..fd3c6b991 100644--- a/tests/services/session/test_attachment_parsing.py+++ b/tests/services/session/test_attachment_parsing.py@@ -41,9 +41,7 @@ async def test_chat_pdf_always_uses_configured_parser(assert path.name == "pdf_notes.pdf"return ParsedDocument(markdown="# Parsed layout\n\n")- monkeypatch.setattr(- "deeptutor.services.session.attachment_parsing.get_parse_service", lambda: Parser()- )+ monkeypatch.setattr("deeptutor.services.parsing.get_parse_service", lambda: Parser())records, contexts = await parse_chat_pdf_attachments([{@@ -73,9 +71,7 @@ async def test_configured_parser_keeps_native_image_page_markers(def parse(self, path: Path, **_: object) -> ParsedDocument:return ParsedDocument(markdown="# Parsed layout")- monkeypatch.setattr(- "deeptutor.services.session.attachment_parsing.get_parse_service", lambda: Parser()- )+ monkeypatch.setattr("deeptutor.services.parsing.get_parse_service", lambda: Parser())native = ("--- Page 1 ---\nNative text\n[图片 1: image-01.png]""\n\n--- Page 2 ---\nMore text\n[图片 1: image-01.png]"@@ -105,9 +101,7 @@ async def test_image_page_markers_survive_parser_text_quota(def parse(self, path: Path, **_: object) -> ParsedDocument:return ParsedDocument(markdown="P" * 500)- monkeypatch.setattr(- "deeptutor.services.session.attachment_parsing.get_parse_service", lambda: Parser()- )+ monkeypatch.setattr("deeptutor.services.parsing.get_parse_service", lambda: Parser())monkeypatch.setattr("deeptutor.services.session.attachment_parsing.get_chat_attachment_limits",lambda: ChatAttachmentLimits(1000, 1000, 120, 120),@@ -146,9 +140,7 @@ async def test_scan_pdf_uses_parser_and_reports_structured_progress(on_output("MinerU page 1/1")return ParsedDocument(markdown="")- monkeypatch.setattr(- "deeptutor.services.session.attachment_parsing.get_parse_service", lambda: Parser()- )+ monkeypatch.setattr("deeptutor.services.parsing.get_parse_service", lambda: Parser())records, contexts = await parse_chat_pdf_attachments([{"id": "scan", "filename": "scan.pdf", "extracted_text": "", "extracted_chars": 0}],attachment_store=store,@@ -178,9 +170,7 @@ async def test_parser_failure_is_not_reported_as_empty_success(def parse(self, path: Path, **_: object) -> ParsedDocument:raise RuntimeError("parser unavailable")- monkeypatch.setattr(- "deeptutor.services.session.attachment_parsing.get_parse_service", lambda: Parser()- )+ monkeypatch.setattr("deeptutor.services.parsing.get_parse_service", lambda: Parser())records, contexts = await parse_chat_pdf_attachments([{"id": "bad", "filename": "bad.pdf"}],attachment_store=store,@@ -205,9 +195,7 @@ async def test_parser_failure_preserves_usable_native_pdf_text(def parse(self, path: Path, **_: object) -> ParsedDocument:raise RuntimeError("configured parser offline")- monkeypatch.setattr(- "deeptutor.services.session.attachment_parsing.get_parse_service", lambda: Parser()- )+ monkeypatch.setattr("deeptutor.services.parsing.get_parse_service", lambda: Parser())records, contexts = await parse_chat_pdf_attachments([{diff --git a/tests/test_packaging_metadata.py b/tests/test_packaging_metadata.pyindex 5c4c87525..ec4fd9b66 100644--- a/tests/test_packaging_metadata.py+++ b/tests/test_packaging_metadata.py@@ -1,270 +1,91 @@-"""Tests for dependency metadata shared by the published packages."""--from __future__ import annotations+"""Published wheel ownership and dependency floors for the modular install."""from pathlib import Pathimport tomllib+from packaging.requirements import Requirementimport pytest-REPOSITORY_ROOT = Path(__file__).resolve().parents[1]---def _project(path: Path) -> dict:- with path.open("rb") as file:- return tomllib.load(file)["project"]---def _cli_requirement_lines() -> list[str]:- return [- line.split("#", 1)[0].strip()- for line in (REPOSITORY_ROOT / "requirements" / "cli.txt")- .read_text(encoding="utf-8")- .splitlines()- if line.split("#", 1)[0].strip()- ]---def test_parser_extras_track_current_upstream_floors() -> None:- extras = _project(REPOSITORY_ROOT / "pyproject.toml")["optional-dependencies"]-- assert extras["parse-markitdown"] == ["markitdown[all]>=0.1.7"]- assert extras["parse-pymupdf4llm"] == ["pymupdf4llm>=1.28.2"]- assert extras["parse-liteparse"] == ["liteparse>=2.14.2"]- assert extras["parse-docling"] == [- "docling[xbrl]>=2.123.1",- "docling-slim[format-iwork,format-opendocument,format-video]>=2.123.1",- ]---def test_python_314_is_supported_by_both_distributions() -> None:- expected = ">=3.11,<3.15"- assert _project(REPOSITORY_ROOT / "pyproject.toml")["requires-python"] == expected- assert (- _project(REPOSITORY_ROOT / "packaging" / "deeptutor-cli" / "pyproject.toml")[- "requires-python"- ]- == expected- )---def test_python_314_rag_dependency_guards_match_every_install_surface() -> None:- bm25 = "llama-index-retrievers-bm25>=0.7.1,<0.8.0; python_version < '3.14'"- faiss = [- "faiss-cpu>=1.8.0,<2.0.0; python_version < '3.14'",- "faiss-cpu>=1.12.0,<2.0.0; python_version >= '3.14'",- ]- root = _project(REPOSITORY_ROOT / "pyproject.toml")- cli_package = _project(REPOSITORY_ROOT / "packaging" / "deeptutor-cli" / "pyproject.toml")+from deeptutor.__version__ import __version__+from deeptutor.modules.catalog import manifests+from scripts.sync_module_requirements import generated- for dependencies in (- root["dependencies"],- root["optional-dependencies"]["cli"],- cli_package["dependencies"],- ):- assert [- item for item in dependencies if item.startswith("llama-index-retrievers-bm25")- ] == [bm25]- assert [item for item in dependencies if item.startswith("faiss-cpu")] == faiss+ROOT = Path(__file__).resolve().parents[1]- requirement_lines = _cli_requirement_lines()- assert [- item for item in requirement_lines if item.startswith("llama-index-retrievers-bm25")- ] == [bm25.replace("'3.14'", '"3.14"')]- assert [item for item in requirement_lines if item.startswith("faiss-cpu")] == [- item.replace("'3.14'", '"3.14"') for item in faiss- ]+def project(path="pyproject.toml"):+ return tomllib.loads((ROOT / path).read_text())["project"]-def test_graphrag_extra_remains_guarded_until_upstream_supports_python_314() -> None:- extras = _project(REPOSITORY_ROOT / "pyproject.toml")["optional-dependencies"]- assert extras["graphrag"] == ["graphrag>=3.0.1,<4.0.0; python_version < '3.14'"]+def test_core_and_cli_have_one_code_owner():+ assert project()["dependencies"] == manifests()["core"]["requirements"]+ cli = tomllib.loads((ROOT / "packaging/deeptutor-cli/pyproject.toml").read_text())+ assert cli["project"]["dependencies"] == [f"deeptutor=={__version__}"]+ assert cli["tool"]["setuptools"]["packages"] == []+ assert "scripts" not in cli["project"]+ for spec in (project(), cli["project"]):+ assert spec["requires-python"] == ">=3.11,<3.15"- "metadata_path",- [- REPOSITORY_ROOT / "pyproject.toml",- REPOSITORY_ROOT / "packaging" / "deeptutor-cli" / "pyproject.toml",- ],-)-def test_typer_dependency_does_not_request_removed_all_extra(metadata_path: Path) -> None:- with metadata_path.open("rb") as file:- dependencies = tomllib.load(file)["project"]["dependencies"]- typer_requirements = [item for item in dependencies if item.startswith("typer")]- assert typer_requirements == ["typer>=0.9.0"]+def test_generated_source_dependency_files_are_current():+ for filename, content in generated().items():+ assert (ROOT / "requirements" / filename).read_text() == content@pytest.mark.parametrize(- "metadata_path",+ "module,requirement",[- REPOSITORY_ROOT / "pyproject.toml",- REPOSITORY_ROOT / "packaging" / "deeptutor-cli" / "pyproject.toml",+ ("core", "mcp>=1.26.0,<2.0.0"),+ ("core", "typer>=0.9.0"),+ ("core", "tzdata>=2024.1"),+ ("core", "packaging>=24.2"),+ ("core", "loguru>=0.7.3,<1.0.0"),+ ("core", "json-repair>=0.57.0,<1.0.0"),+ ("core", "pyte>=0.8.1"),+ ("partners", "qrcode>=7.4.0,<9.0.0"),+ ("knowledge", "pageindex>=0.2.10,<0.3.0"),+ ("calendar", "croniter>=6.0.0,<7.0.0"),+ ("parsing", "pdfplumber>=0.11.0"),+ ("parsing", "reportlab>=4.0.0"),+ ("parser-markitdown", "markitdown[all]>=0.1.7"),+ ("parser-pymupdf4llm", "pymupdf4llm>=1.28.2"),+ ("parser-liteparse", "liteparse>=2.14.2"),+ ("parser-docling", "docling[xbrl]>=2.123.1"),+ ("parser-docling", "docling-slim[format-iwork,format-opendocument,format-video]>=2.123.1"),],)-def test_mcp_client_is_a_core_dependency(metadata_path: Path) -> None:- """`mcp` must install by default, not only via an extra (issue #792).-- Both distributions ship the configurable MCP tool surface. An extra-gated- client would leave ordinary configured servers failing with- ``ModuleNotFoundError`` on a plain install.- """- with metadata_path.open("rb") as file:- dependencies = tomllib.load(file)["project"]["dependencies"]-- mcp_requirements = [item for item in dependencies if item.split(">")[0].strip() == "mcp"]- assert mcp_requirements == ["mcp>=1.26.0,<2.0.0"]---def test_partners_extra_does_not_redeclare_the_core_mcp_client() -> None:- """The `partners` extra is IM channel SDKs only; `mcp` is core now."""- with (REPOSITORY_ROOT / "pyproject.toml").open("rb") as file:- extras = tomllib.load(file)["project"]["optional-dependencies"]-- assert not [item for item in extras["partners"] if item.split(">")[0].strip() == "mcp"]---def test_requirements_mirror_the_core_mcp_client() -> None:- """Docker/CI installs read requirements/, which must agree with pyproject."""- requirements = REPOSITORY_ROOT / "requirements"- cli_text = (requirements / "cli.txt").read_text(encoding="utf-8")- partners_text = (requirements / "partners.txt").read_text(encoding="utf-8")-- # cli.txt mirrors the core dependency set, so the client belongs there...- assert "mcp>=1.26.0,<2.0.0" in cli_text- # ...and partners.txt inherits it transitively rather than redeclaring it.- assert "-r server.txt" in partners_text- assert "mcp>=" not in partners_text---def test_cli_qrcode_dependency_matches_every_install_surface() -> None:- """Plain CLI installs include the QR renderer used by partner onboarding."""- expected = "qrcode>=7.4.0,<9.0.0"- root = _project(REPOSITORY_ROOT / "pyproject.toml")- cli_package = _project(REPOSITORY_ROOT / "packaging" / "deeptutor-cli" / "pyproject.toml")-- assert root["dependencies"].count(expected) == 1- assert cli_package["dependencies"].count(expected) == 1- assert _cli_requirement_lines().count(expected) == 1---def test_full_app_cron_dependency_matches_every_server_install_surface() -> None:- expected = "croniter>=6.0.0,<7.0.0"- with (REPOSITORY_ROOT / "pyproject.toml").open("rb") as file:- project = tomllib.load(file)["project"]-- assert project["dependencies"].count(expected) == 1- assert project["optional-dependencies"]["server"].count(expected) == 1- assert (REPOSITORY_ROOT / "requirements" / "server.txt").read_text(- encoding="utf-8"- ).splitlines().count(expected) == 1---def test_pageindex_sdk_range_matches_every_install_surface() -> None:- expected = "pageindex>=0.2.10,<0.3.0"- with (REPOSITORY_ROOT / "pyproject.toml").open("rb") as file:- root = tomllib.load(file)["project"]- with (REPOSITORY_ROOT / "packaging" / "deeptutor-cli" / "pyproject.toml").open("rb") as file:- cli_package = tomllib.load(file)["project"]-- assert root["dependencies"].count(expected) == 1- assert root["optional-dependencies"]["cli"].count(expected) == 1- assert cli_package["dependencies"].count(expected) == 1- assert (REPOSITORY_ROOT / "requirements" / "cli.txt").read_text(- encoding="utf-8"- ).splitlines().count(expected) == 1---def test_lightrag_extra_is_the_exact_native_sdk_without_parser_transitives() -> None:- with (REPOSITORY_ROOT / "pyproject.toml").open("rb") as file:- extras = tomllib.load(file)["project"]["optional-dependencies"]-- requirements = extras["rag-lightrag"]- assert requirements == ["lightrag-hku==1.5.7"]- names = [requirement.lower().split("=", 1)[0].split("<", 1)[0] for requirement in requirements]- assert "raganything" not in names- assert "mineru" not in names--- "expected",- [- "packaging>=24.2",- "loguru>=0.7.3,<1.0.0",- "json-repair>=0.57.0,<1.0.0",- "pyte>=0.8.1",- "pdfplumber>=0.11.0",- "reportlab>=4.0.0",- ],-)-def test_cli_runtime_dependencies_match_every_install_surface(expected: str) -> None:- """CLI-only installs must include everything used by terminal workflows."""- with (REPOSITORY_ROOT / "pyproject.toml").open("rb") as file:- root = tomllib.load(file)["project"]- with (REPOSITORY_ROOT / "packaging" / "deeptutor-cli" / "pyproject.toml").open("rb") as file:- cli_package = tomllib.load(file)["project"]-- assert root["dependencies"].count(expected) == 1- assert cli_package["dependencies"].count(expected) == 1- requirement_lines = [- line.split("#", 1)[0].strip()- for line in (REPOSITORY_ROOT / "requirements" / "cli.txt")- .read_text(encoding="utf-8")- .splitlines()- ]- assert requirement_lines.count(expected) == 1---def test_timezone_database_is_installed_on_every_install_surface() -> None:- """Windows has no system zoneinfo database, so named zones need ``tzdata``.-- Without it ``ZoneInfo("UTC")`` raises on Windows and the usage statistics,- practice review and cron features reject every timezone (issue #1907).- """- expected = "tzdata>=2024.1"- root = _project(REPOSITORY_ROOT / "pyproject.toml")- cli_package = _project(REPOSITORY_ROOT / "packaging" / "deeptutor-cli" / "pyproject.toml")-- assert root["dependencies"].count(expected) == 1- assert cli_package["dependencies"].count(expected) == 1- assert _cli_requirement_lines().count(expected) == 1---def test_windows_mineru_worker_dependencies_match_every_install_surface() -> None:- from packaging.requirements import Requirement+def test_dependency_floor_belongs_to_its_module(module, requirement):+ assert manifests()[module]["requirements"].count(requirement) == 1+ if module != "core":+ assert requirement not in project()["dependencies"]+++def test_python_314_rag_guards_are_preserved():+ dependencies = [Requirement(raw) for raw in manifests()["knowledge"]["requirements"]]+ for version, minimum in [("3.13", "1.8.0"), ("3.14", "1.12.0")]:+ faiss = [+ r+ for r in dependencies+ if r.name == "faiss-cpu" and r.marker.evaluate({"python_version": version})+ ]+ assert len(faiss) == 1+ assert minimum in faiss[0].specifier+ bm25 = next(r for r in dependencies if r.name == "llama-index-retrievers-bm25")+ assert not bm25.marker.evaluate({"python_version": "3.14"})+ lexical = next(r for r in dependencies if r.name == "bm25s")+ assert lexical.marker is None or lexical.marker.evaluate({"python_version": "3.14"})- root = _project(REPOSITORY_ROOT / "pyproject.toml")- cli_package = _project(REPOSITORY_ROOT / "packaging" / "deeptutor-cli" / "pyproject.toml")- for dependencies in (- root["dependencies"],- root["optional-dependencies"]["cli"],- cli_package["dependencies"],- _cli_requirement_lines(),- ):- requirements = {- requirement.name: requirement- for line in dependencies- if not line.startswith("-")- for requirement in [Requirement(line)]- }- assert "psutil" in requirements- win32 = requirements["pywin32"]- assert win32.marker.evaluate({"sys_platform": "win32"})- assert not win32.marker.evaluate({"sys_platform": "linux"})- assert not win32.marker.evaluate({"sys_platform": "darwin"})+def test_windows_parser_worker_dependency_is_scoped():+ win32 = next(+ Requirement(r) for r in manifests()["parsing"]["requirements"] if r.startswith("pywin32")+ )+ assert win32.marker.evaluate({"sys_platform": "win32"})+ assert not win32.marker.evaluate({"sys_platform": "darwin"})+ assert any(r.startswith("psutil") for r in manifests()["core"]["requirements"])-def test_legacy_page_lexical_engine_is_available_on_every_supported_python() -> None:- from packaging.requirements import Requirement- root = _project(REPOSITORY_ROOT / "pyproject.toml")- cli = _project(REPOSITORY_ROOT / "packaging" / "deeptutor-cli" / "pyproject.toml")- for dependencies in (- root["dependencies"],- root["optional-dependencies"]["cli"],- cli["dependencies"],- _cli_requirement_lines(),- ):- engine = next(Requirement(line) for line in dependencies if line.startswith("bm25s"))- assert engine.marker is None or engine.marker.evaluate({"python_version": "3.14"})+def test_optional_sdk_constraints_remain_intact():+ extras = project()["optional-dependencies"]+ assert extras["rag-lightrag"] == ["lightrag-hku==1.5.7"]+ assert extras["graphrag"] == ["graphrag>=3.0.1,<4.0.0; python_version < '3.14'"]diff --git a/tests/tools/test_office_artifact_execution.py b/tests/tools/test_office_artifact_execution.pyindex fe3cb1fca..d9f3d5b5b 100644--- a/tests/tools/test_office_artifact_execution.py+++ b/tests/tools/test_office_artifact_execution.py@@ -229,14 +229,29 @@ def test_office_skills_reuse_the_shared_workspace_contract() -> None:def test_docx_xlsx_dependencies_cover_pip_source_cli_and_docker() -> None:root = Path(__file__).parents[2]- manifests = {- "pip/source": root / "pyproject.toml",- "pip cli": root / "packaging" / "deeptutor-cli" / "pyproject.toml",- "requirements": root / "requirements" / "cli.txt",- "docker runner": root / "Dockerfile.runner",- }- for deployment, path in manifests.items():- text = path.read_text(encoding="utf-8").lower()+ import tomllib++ core = tomllib.loads((root / "pyproject.toml").read_text())["project"]+ cli = tomllib.loads((root / "packaging/deeptutor-cli/pyproject.toml").read_text())["project"]+ from deeptutor.__version__ import __version__++ assert cli["dependencies"] == [f"deeptutor=={__version__}"]++ def requirements(path):+ lines = []+ for line in path.read_text().splitlines():+ if line.startswith("-r "):+ lines.extend(requirements(path.parent / line[3:].strip()).splitlines())+ else:+ lines.append(line)+ return "\n".join(lines).lower()++ for deployment, text in {+ "core and CLI wheel": "\n".join(core["dependencies"]),+ "source CLI": requirements(root / "requirements/cli.txt"),+ "full source and Docker": requirements(root / "requirements.txt"),+ "docker runner": (root / "Dockerfile.runner").read_text(),+ }.items():assert "python-docx" in text, deploymentassert "openpyxl" in text, deploymentdiff --git a/web/components/access/CapabilityGate.tsx b/web/components/access/CapabilityGate.tsxindex 9e4123da1..ba0cdafd8 100644--- a/web/components/access/CapabilityGate.tsx+++ b/web/components/access/CapabilityGate.tsx@@ -1,5 +1,7 @@"use client";+import { useModules, moduleRouteAvailable } from "@/hooks/useModules";+import { useTranslation } from "react-i18next";import { usePathname } from "next/navigation";import { capabilityForPath } from "@/lib/capability-routes";@@ -18,6 +20,13 @@ export default function CapabilityGate({}) {const pathname = usePathname() ?? "";const capability = capabilityForPath(pathname);+ const { modules, error, reload } = useModules();+ const { t } = useTranslation();+ if (error) return <button onClick={reload}>{t("Retry")}</button>;+ if (!modules) return <div aria-busy="true">{t("Loading...")}</div>;+ if (!moduleRouteAvailable(pathname, modules)) {+ return <p className="p-6">{t("This module is not installed or is disabled.")}</p>;+ }return (<RequireCapability capability={capability}>{children}</RequireCapability>);diff --git a/web/components/settings/ModulesPanel.tsx b/web/components/settings/ModulesPanel.tsxnew file mode 100644index 000000000..6b61fb919--- /dev/null+++ b/web/components/settings/ModulesPanel.tsx@@ -0,0 +1,36 @@+"use client";++import { useTranslation } from "react-i18next";+import { useModules } from "@/hooks/useModules";++export default function ModulesPanel() {+ const { t } = useTranslation();+ const { modules, error, reload } = useModules();+ return (+ <section className="my-6 rounded-xl border p-5">+ <h2 className="text-lg font-semibold">{t("Modules")}</h2>+ <p className="my-2 text-sm text-[var(--muted-foreground)]">+ {t("Stop DeepTutor before changing modules. Removing a module keeps your data.")}+ </p>+ {error && <button onClick={reload}>{t("Retry")}</button>}+ {!modules && !error && <p aria-busy="true">{t("Loading...")}</p>}+ <div className="overflow-x-auto">+ <table className="w-full text-left text-sm">+ <thead><tr>+ <th className="py-2">{t("Module")}</th><th>{t("Installed")}</th>+ <th>{t("Enabled")}</th><th>{t("Ready")}</th><th>{t("Command")}</th>+ </tr></thead>+ <tbody>{modules?.map(module => <tr key={module.id} className="border-t align-top">+ <td className="py-2 pr-3"><code>{module.id}</code>+ {module.issues.map(issue => <p key={issue} className="max-w-md text-xs text-[var(--muted-foreground)]">{issue}</p>)}+ </td>+ {[module.installed, module.enabled, module.ready].map((value, index) =>+ <td className="py-2 pr-3" key={index}>{value ? t("Yes") : t("No")}</td>)}+ <td className="py-2"><code>{module.id === "core" ? "—" :+ `deeptutor module ${!module.installed ? "install" : !module.enabled ? "enable" : "disable"} ${module.id}`}</code></td>+ </tr>)}</tbody>+ </table>+ </div>+ </section>+ );+}diff --git a/web/components/settings/SettingsRuntimePage.tsx b/web/components/settings/SettingsRuntimePage.tsxindex 928677410..51724b887 100644--- a/web/components/settings/SettingsRuntimePage.tsx+++ b/web/components/settings/SettingsRuntimePage.tsx@@ -2,6 +2,7 @@import { useTranslation } from "react-i18next";import { SettingsPageHeader } from "./shared";+import ModulesPanel from "./ModulesPanel";import SettingsStatusPanel from "./SettingsStatusPanel";import SettingsReadinessPanel from "./SettingsReadinessPanel";import { useSettings } from "@/features/settings/store/SettingsStore";@@ -17,6 +18,7 @@ export default function SettingsRuntimePage() {"Check configured services and resolve connection problems.",)}/>+ <ModulesPanel /><SettingsStatusPanel /><SettingsReadinessPanel enabled={catalogEditable === true} /></div>diff --git a/web/components/sidebar/SidebarNav.tsx b/web/components/sidebar/SidebarNav.tsxindex bb06cd2e5..6b6eda3f5 100644--- a/web/components/sidebar/SidebarNav.tsx+++ b/web/components/sidebar/SidebarNav.tsx@@ -45,6 +45,7 @@ import {isNavActive,navVisibleUnderPolicy,} from "@/components/sidebar/nav-entries";+import { useModules, moduleRouteAvailable } from "@/hooks/useModules";import { useAuthStatus } from "@/hooks/useAuthStatus";import { Tooltip } from "@/shared/ui/Tooltip";import { useDragSort, type DragSort } from "@/hooks/useDragSort";@@ -112,12 +113,14 @@ export function SidebarNav({}, []);const { learningPolicy } = useAuthStatus();+ const { modules } = useModules();const moduleHrefs = useMemo(() =>MODULE_NAV_HREFS.filter((href) =>+ modules !== null && moduleRouteAvailable(href, modules) &&navVisibleUnderPolicy(href, learningPolicy?.allowedSurfaces ?? null),),- [learningPolicy],+ [learningPolicy, modules],);const resolved = useMemo(() => resolveNavLayout(moduleHrefs, layout, DEFAULT_COLLAPSED_NAV),@@ -538,6 +541,7 @@ export function SidebarHome({const pathname = usePathname();const { has } = useCapabilityAccess();const { learningPolicy } = useAuthStatus();+ const { modules } = useModules();const entry = NAV_BY_HREF.get("/chat")!;if (learningPolicy &&diff --git a/web/features/calendar/components/CalendarRuntime.tsx b/web/features/calendar/components/CalendarRuntime.tsxindex f73fa8d64..641c8654f 100644--- a/web/features/calendar/components/CalendarRuntime.tsx+++ b/web/features/calendar/components/CalendarRuntime.tsx@@ -1,5 +1,6 @@'use client'+import { useModules } from '@/hooks/useModules'import { browserStorage } from '@/shared/storage'import { useEffect, type ReactNode } from 'react'import { useTranslation } from 'react-i18next'@@ -13,7 +14,9 @@ import { browserTimeZone, formatTime } from '../model/dates'export default function CalendarRuntime({ children }: { children: ReactNode }) {const { t, i18n } = useTranslation()const { loading, learningPolicy, enabled: authEnabled, authenticated } = useAuthStatus()+ const { modules } = useModules()const enabled =+ Boolean(modules?.some(module => module.id === 'calendar' && module.enabled)) &&!loading &&(!authEnabled || authenticated) &&(!learningPolicy || learningPolicy.allowedSurfaces.includes('chat'))diff --git a/web/hooks/useModules.ts b/web/hooks/useModules.tsnew file mode 100644index 000000000..94a48c615--- /dev/null+++ b/web/hooks/useModules.ts@@ -0,0 +1,55 @@+'use client'++import { useEffect, useState, useCallback } from 'react'+import { apiFetch, apiUrl } from '@/lib/api'++export interface ModuleStatus {+ id: string+ installed: boolean+ enabled: boolean+ ready: boolean+ navigation: string[]+ issues: string[]+}++export function moduleRouteAvailable(path: string, modules: ModuleStatus[]): boolean {+ const owners = modules.filter(module => module.navigation.some(+ prefix => path === prefix || path.startsWith(`${prefix}/`)+ ))+ return owners.length === 0 || owners.every(module => module.installed && module.enabled)+}++// One deployment inventory request serves the sidebar, route gate and runtimes.+// A focus/retry refresh observes a server restarted with a different selection.+let pending: Promise<ModuleStatus[]> | null = null+function readModules() {+ if (!pending) {+ pending = apiFetch(apiUrl('/api/modules'))+ .then(async response => {+ if (!response.ok) throw new Error('Module inventory unavailable')+ const result = await response.json() as { modules: ModuleStatus[] }+ return result.modules+ })+ }+ return pending+}++export function useModules() {+ const [modules, setModules] = useState<ModuleStatus[] | null>(null)+ const [error, setError] = useState(false)+ const [revision, setRevision] = useState(0)+ const reload = useCallback(() => {+ pending = null+ setError(false)+ setRevision(value => value + 1)+ }, [])+ useEffect(() => {+ let active = true+ void readModules()+ .then(result => { if (active) setModules(result) })+ .catch(() => { if (active) setError(true) })+ window.addEventListener('focus', reload)+ return () => { active = false; window.removeEventListener('focus', reload) }+ }, [revision, reload])+ return { modules, error, reload, available: (path: string) => modules !== null && moduleRouteAvailable(path, modules) }+}diff --git a/web/locales/de/app.json b/web/locales/de/app.jsonindex 85079c2e8..6f7f2c347 100644--- a/web/locales/de/app.json+++ b/web/locales/de/app.json@@ -6170,5 +6170,9 @@"Turn a question into an animated explainer you can play": "Verwandle eine Frage in ein abspielbares Erklär-Video","View Remotion Code": "Remotion-Code anzeigen","{{seconds}} s": "{{seconds}} s",- "Fixed after {{count}} checks": "Nach {{count}} Prüfungen korrigiert"+ "Fixed after {{count}} checks": "Nach {{count}} Prüfungen korrigiert",+ "Modules": "Modules",+ "Module": "Module",+ "Stop DeepTutor before changing modules. Removing a module keeps your data.": "Stop DeepTutor before changing modules. Removing a module keeps your data.",+ "This module is not installed or is disabled.": "This module is not installed or is disabled."}diff --git a/web/locales/en/app.json b/web/locales/en/app.jsonindex ecd2a5237..c587ff948 100644--- a/web/locales/en/app.json+++ b/web/locales/en/app.json@@ -6170,5 +6170,9 @@"Turn a question into an animated explainer you can play": "Turn a question into an animated explainer you can play","View Remotion Code": "View Remotion Code","{{seconds}} s": "{{seconds}} s",- "Fixed after {{count}} checks": "Fixed after {{count}} checks"+ "Fixed after {{count}} checks": "Fixed after {{count}} checks",+ "Modules": "Modules",+ "Module": "Module",+ "Stop DeepTutor before changing modules. Removing a module keeps your data.": "Stop DeepTutor before changing modules. Removing a module keeps your data.",+ "This module is not installed or is disabled.": "This module is not installed or is disabled."}diff --git a/web/locales/fr/app.json b/web/locales/fr/app.jsonindex 7bd5662df..f72495d7f 100644--- a/web/locales/fr/app.json+++ b/web/locales/fr/app.json@@ -6324,5 +6324,9 @@"Turn a question into an animated explainer you can play": "Transformer une question en animation explicative à regarder","View Remotion Code": "Voir le code Remotion","{{seconds}} s": "{{seconds}} s",- "Fixed after {{count}} checks": "Corrigé après {{count}} vérifications"+ "Fixed after {{count}} checks": "Corrigé après {{count}} vérifications",+ "Modules": "Modules",+ "Module": "Module",+ "Stop DeepTutor before changing modules. Removing a module keeps your data.": "Stop DeepTutor before changing modules. Removing a module keeps your data.",+ "This module is not installed or is disabled.": "This module is not installed or is disabled."}diff --git a/web/locales/pl/app.json b/web/locales/pl/app.jsonindex 045344460..13bd6efcb 100644--- a/web/locales/pl/app.json+++ b/web/locales/pl/app.json@@ -6192,5 +6192,9 @@"Turn a question into an animated explainer you can play": "Zamień pytanie w animowane wyjaśnienie do odtworzenia","View Remotion Code": "Pokaż kod Remotion","{{seconds}} s": "{{seconds}} s",- "Fixed after {{count}} checks": "Poprawiono po {{count}} sprawdzeniach"+ "Fixed after {{count}} checks": "Poprawiono po {{count}} sprawdzeniach",+ "Modules": "Modules",+ "Module": "Module",+ "Stop DeepTutor before changing modules. Removing a module keeps your data.": "Stop DeepTutor before changing modules. Removing a module keeps your data.",+ "This module is not installed or is disabled.": "This module is not installed or is disabled."}diff --git a/web/locales/uk/app.json b/web/locales/uk/app.jsonindex ece7926f5..d1ac0bbbe 100644--- a/web/locales/uk/app.json+++ b/web/locales/uk/app.json@@ -6192,5 +6192,9 @@"Turn a question into an animated explainer you can play": "Перетворіть запитання на анімоване пояснення, яке можна відтворити","View Remotion Code": "Переглянути код Remotion","{{seconds}} s": "{{seconds}} с",- "Fixed after {{count}} checks": "Виправлено після {{count}} перевірок"+ "Fixed after {{count}} checks": "Виправлено після {{count}} перевірок",+ "Modules": "Modules",+ "Module": "Module",+ "Stop DeepTutor before changing modules. Removing a module keeps your data.": "Stop DeepTutor before changing modules. Removing a module keeps your data.",+ "This module is not installed or is disabled.": "This module is not installed or is disabled."}diff --git a/web/locales/zh/app.json b/web/locales/zh/app.jsonindex 93ccc82a2..dda0d7704 100644--- a/web/locales/zh/app.json+++ b/web/locales/zh/app.json@@ -6170,5 +6170,9 @@"Turn a question into an animated explainer you can play": "把问题做成可以播放的讲解动画","View Remotion Code": "查看 Remotion 代码","{{seconds}} s": "{{seconds}} 秒",- "Fixed after {{count}} checks": "经 {{count}} 轮检查修复"+ "Fixed after {{count}} checks": "经 {{count}} 轮检查修复",+ "Modules": "模块",+ "Module": "模块",+ "Stop DeepTutor before changing modules. Removing a module keeps your data.": "更改模块前请停止 DeepTutor。卸载模块会保留你的数据。",+ "This module is not installed or is disabled.": "此模块尚未安装或已禁用。"}diff --git a/web/tests/modules.spec.ts b/web/tests/modules.spec.tsnew file mode 100644index 000000000..98b36d2d6--- /dev/null+++ b/web/tests/modules.spec.ts@@ -0,0 +1,19 @@+import { describe, expect, it } from 'vitest'+import { moduleRouteAvailable, type ModuleStatus } from '@/hooks/useModules'++const reading: ModuleStatus = {+ id: 'reading', installed: false, enabled: false, ready: false,+ navigation: ['/learning/reading', '/learning/watching'], issues: [],+}+describe('module navigation ownership', () => {+ it('blocks absent module pages including nested direct URLs', () => {+ expect(moduleRouteAvailable('/learning/reading/materials/item', [reading])).toBe(false)+ expect(moduleRouteAvailable('/learning/watching', [reading])).toBe(false)+ expect(moduleRouteAvailable('/chat', [reading])).toBe(true)+ expect(moduleRouteAvailable('/learning/reading-list', [reading])).toBe(true)+ })+ it('distinguishes enabled modules from execution readiness', () => {+ expect(moduleRouteAvailable('/learning/reading', [{ ...reading, installed: true, enabled: true }])).toBe(true)+ expect(moduleRouteAvailable('/learning/reading', [{ ...reading, installed: true }])).toBe(false)+ })+})