Skip to content

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

feat: modularize installation and enforce feature dependency boundaries

Bingxi Zhao (Frank)fbab59acbf2e
diff --git a/.github/workflows/modules.yml b/.github/workflows/modules.yml
new file mode 100644
index 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 --extended
diff --git a/.github/workflows/pypi-release.yml b/.github/workflows/pypi-release.yml
index 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 tools
run: |
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__.py
id: version
@@ -148,12 +146,7 @@ jobs:
run: |
set -euo pipefail
mkdir -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 metadata
run: |
@@ -175,7 +168,7 @@ jobs:
raise SystemExit(f"Missing expected distributions: {missing}")
PY
- - name: Publish deeptutor to PyPI
+ - name: Publish module distributions to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
with:
packages-dir: dist/deeptutor/
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 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 configuration
run: |
mkdir -p data/user/settings
@@ -238,14 +238,14 @@ jobs:
uses: actions/cache@v4
with:
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 check
run: |
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@v4
with:
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 dependencies
run: |
python -m pip install --upgrade pip
- pip install -r requirements/server.txt
+ pip install -r requirements/full.txt
pip install -r requirements/partners.txt
pip 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 timeout
env:
DEEPTUTOR_TEST_VIDEO_SANDBOX: "1"
diff --git a/.gitignore b/.gitignore
index 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
.Python
build/
develop-eggs/
diff --git a/MANIFEST.in b/MANIFEST.in
index 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 *.toml
diff --git a/README.md b/README.md
index 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`).
```bash
mkdir -p my-deeptutor && cd my-deeptutor
-pip install -U deeptutor
+pip install -U "deeptutor[full]"
deeptutor init # prompts for ports + LLM provider + optional embedding/search
deeptutor start # starts backend + frontend; keep the terminal open
```
@@ -356,7 +356,8 @@ python3 -m venv .venv && source .venv/bin/activate
python -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 supported
pip install -e ".[graphrag]" # Microsoft GraphRAG engine (Python 3.11–3.13)
pip install -e ".[dev]" # tests/lint tools
pip 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-learning
pip install -e ".[matrix]" # Matrix channel without E2EE/libolm
pip install -e ".[matrix-e2e]" # Matrix E2EE; requires libolm
pip 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.
```bash
git clone https://github.com/HKUDS/DeepTutor.git
@@ -523,7 +524,7 @@ cd DeepTutor
python3 -m venv .venv-cli && source .venv-cli/bin/activate
python -m pip install --upgrade pip
-python -m pip install -e ./packaging/deeptutor-cli
+python -m pip install -e .
deeptutor init --cli
deeptutor 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.py
new file mode 100644
index 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.py
index c64fa9241..a6b1f4904 100644
--- a/deeptutor/agents/_shared/tool_composition.py
+++ b/deeptutor/agents/_shared/tool_composition.py
@@ -25,6 +25,7 @@ from dataclasses import dataclass
import json
from typing import Any
+from deeptutor.modules.catalog import module_enabled
from 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 False
from deeptutor.services.memory import get_memory_store
store = 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 False
from deeptutor.services.notebook import get_notebook_manager
notebooks = 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 False
from deeptutor.learning.navigation import learner_has_topics
return learner_has_topics()
diff --git a/deeptutor/agents/chat/capability.py b/deeptutor/agents/chat/capability.py
index 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 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_manifest
from deeptutor.runtime.stream_bus import StreamBus
class 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.py
index 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_kb
from deeptutor.services.rag.factory import PAGEINDEX_OSS_PROVIDER, PAGEINDEX_PROVIDER
from 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_kb
return [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.py
index 6883acb6a..98508ac1e 100644
--- a/deeptutor/agents/math_animator/capability.py
+++ b/deeptutor/agents/math_animator/capability.py
@@ -7,36 +7,17 @@ import time
from typing import Any
from deeptutor.agents._shared.capability_result import emit_capability_result
-from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability
+from deeptutor.core.capability_protocol import TurnCapability
from deeptutor.core.context import UnifiedContext
from deeptutor.core.trace import build_trace_metadata, merge_trace_metadata, new_call_id
from deeptutor.i18n import StatusI18n
from 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_manifest
from deeptutor.runtime.stream_bus import StreamBus
class 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.py
index f5702e638..6e53dd3ac 100644
--- a/deeptutor/agents/math_animator/renderer.py
+++ b/deeptutor/agents/math_animator/renderer.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import asyncio
+import os
from pathlib import Path
import re
import 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)
+ raise
await 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.py
index 3687ec16f..c48c4f174 100644
--- a/deeptutor/agents/question/capability.py
+++ b/deeptutor/agents/question/capability.py
@@ -17,24 +17,17 @@ import tempfile
from typing import Any
from deeptutor.agents._shared.capability_result import emit_capability_result
-from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability
+from deeptutor.core.capability_protocol import TurnCapability
from deeptutor.core.context import UnifiedContext
from deeptutor.core.trace import merge_trace_metadata
from deeptutor.i18n import StatusI18n
from 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_manifest
from deeptutor.runtime.stream_bus import StreamBus
class 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_config
diff --git a/deeptutor/agents/question/pipeline.py b/deeptutor/agents/question/pipeline.py
index 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.py
index 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 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_manifest
from deeptutor.runtime.stream_bus import StreamBus
from deeptutor.services.config import load_config_with_main
class 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 None
diff --git a/deeptutor/agents/research/pipeline.py b/deeptutor/agents/research/pipeline.py
index 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.py
index dacc56e05..9215cb229 100644
--- a/deeptutor/agents/video_lesson/capability.py
+++ b/deeptutor/agents/video_lesson/capability.py
@@ -7,27 +7,19 @@ import time
from typing import Any
from deeptutor.agents._shared.capability_result import emit_capability_result
-from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability
+from deeptutor.core.capability_protocol import TurnCapability
from deeptutor.core.context import UnifiedContext
from deeptutor.core.trace import merge_trace_metadata
from deeptutor.i18n import StatusI18n
from 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_manifest
from deeptutor.runtime.stream_bus import StreamBus
MAX_ATTEMPTS = 3
class 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 LessonWriterAgent
diff --git a/deeptutor/agents/visualize/capability.py b/deeptutor/agents/visualize/capability.py
index 32b247740..3f2c159ab 100644
--- a/deeptutor/agents/visualize/capability.py
+++ b/deeptutor/agents/visualize/capability.py
@@ -7,14 +7,14 @@ import logging
from typing import Any
from deeptutor.agents._shared.capability_result import emit_capability_result
-from deeptutor.core.capability_protocol import CapabilityManifest, TurnCapability
+from deeptutor.core.capability_protocol import TurnCapability
from deeptutor.core.context import UnifiedContext
from deeptutor.core.trace import merge_trace_metadata
from deeptutor.i18n import StatusI18n
from deeptutor.runtime.agentic.usage import UsageTracker
+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifest
from 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.util
import 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.py
index 27446f237..d167f447c 100644
--- a/deeptutor/api/main.py
+++ b/deeptutor/api/main.py
@@ -3,12 +3,13 @@ from contextlib import asynccontextmanager
import logging
import sys
-from fastapi import Depends, FastAPI, Request
+from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse, RedirectResponse
from deeptutor.api.security_guard import install_security_guard
from deeptutor.logging import configure_logging
+from deeptutor.modules.catalog import module_enabled
from 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_container
await 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 BackgroundCommandKind
async 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_service
get_cron_service().reload()
return
+ from deeptutor.modules.catalog import require_module
+
+ require_module("partners")
from deeptutor.services.partners import get_partner_manager
manager = get_partner_manager()
@@ -268,42 +233,34 @@ async def lifespan(app: FastAPI):
cron_service = None
try:
- 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_change
except Exception:
logger.exception("Failed to configure cron change notifications")
+ from deeptutor.modules.services import module_service_callbacks
from deeptutor.runtime.background_leader import BackgroundLeaderSupervisor
background_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 = False
logger.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/112
redirect_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.py
new file mode 100644
index 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.json
index 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.py
index 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 copy
import hashlib
from importlib import import_module
import 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] = router
self.app.include_router(router, **options)
diff --git a/deeptutor/api/routers/dashboard.py b/deeptutor/api/routers/dashboard.py
index 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_enabled
from deeptutor.multi_user.learning_access import learning_surface_allowed
async 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):
continue
try:
result[kind] = await _workspace_rows(reader)
diff --git a/deeptutor/api/routers/knowledge.py b/deeptutor/api/routers/knowledge.py
index 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 FileTypeRouter
from 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 DocumentValidator
from deeptutor.utils.error_utils import format_exception_message
+from deeptutor.utils.file_types import FileTypeRouter
# Initialize logger with config
config = load_config_with_main("main.yaml", PROJECT_ROOT)
diff --git a/deeptutor/api/routers/modules.py b/deeptutor/api/routers/modules.py
new file mode 100644
index 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.py
index 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, HTTPException
from pydantic import BaseModel, Field, StrictBool, field_validator
from deeptutor.api.routers.auth import require_admin, require_auth
-from deeptutor.knowledge.manager import KnowledgeBaseManager
+from deeptutor.modules.catalog import module_enabled, require_module
from deeptutor.multi_user.audit import log_admin_action, log_guardian_action
from 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_registry
from deeptutor.services.auth import POCKETBASE_ENABLED, hash_password
from 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: no
channel wiring or model selection leaks into the assignable summary.
"""
+ if not module_enabled("partners"):
+ return []
from deeptutor.services.partners import get_partner_manager
admin_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 None
if 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.py
index 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_none
from deeptutor.multi_user.partner_access import visible_partners
from deeptutor.multi_user.paths import get_current_path_service, get_path_service_for_scope
from deeptutor.services.auth import TokenPayload
-from deeptutor.services.partners.scope import partner_scope
from deeptutor.services.path_service import PathService
router = APIRouter()
@@ -58,10 +57,13 @@ def _resolve_partner_output(relative_path: str) -> Path | None:
the same relative path colliding across multiple partners is vanishingly
unlikely. Fail closed anyway: only a unique partner match is served.
"""
+ from deeptutor.modules.catalog import module_enabled
from 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.py
index 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, Request
from pydantic import BaseModel, Field, field_validator
from 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_enabled
from deeptutor.response_languages import validate_reply_language_override
from deeptutor.services.session import get_session_store, get_sqlite_session_store
from 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.py
index 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 call
time 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_id
if is_partner_user_id(get_current_user().id):
raise HTTPException(
diff --git a/deeptutor/api/routers/subagents.py b/deeptutor/api/routers/subagents.py
index 1b631be1b..a7349da81 100644
--- a/deeptutor/api/routers/subagents.py
+++ b/deeptutor/api/routers/subagents.py
@@ -23,9 +23,7 @@ from fastapi.responses import StreamingResponse
from pydantic import BaseModel, Field
from deeptutor.api.routers.auth import require_admin
-from deeptutor.knowledge.kb_types import SUBAGENT_KB_TYPE
from deeptutor.multi_user.knowledge_access import account_kb_manager
-from deeptutor.services.rag.linked_kb import assert_path_allowed
from 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.py
index 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_auth
from deeptutor.multi_user.partner_access import visible_partners
from deeptutor.multi_user.paths import user_context
from deeptutor.services.auth import TokenPayload
-from deeptutor.services.partners.scope import partner_user
from 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.py
index 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
@classmethod
def 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
+ raise
async 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 = None
async 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_sessions
from deeptutor.multi_user.paths import user_context
from deeptutor.services.workspace import get_content_workspace_service
diff --git a/deeptutor/app/facade.py b/deeptutor/app/facade.py
index e3dd1d5d3..c6ac9600a 100644
--- a/deeptutor/app/facade.py
+++ b/deeptutor/app/facade.py
@@ -4,14 +4,10 @@ from __future__ import annotations
from dataclasses import asdict, dataclass
from functools import wraps
-import importlib.util
import inspect
import json
-import shutil
from typing import Any, AsyncIterator
-from deeptutor.services.notebook import get_notebook_manager
-
from .container import get_application_container
from .contracts import TurnRequest
@@ -77,6 +73,11 @@ class DeepTutorApp:
@property
def 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.py
index 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.py
index 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 dataclass
import re
from 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 BookContextResult
def normalize_book_references(value: Any) -> list[NormalizedBookReference]:
diff --git a/deeptutor/book/inputs.py b/deeptutor/book/inputs.py
index 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_manager
diff --git a/deeptutor/capabilities/ask_questions/capability.py b/deeptutor/capabilities/ask_questions/capability.py
index 1ffea8ea1..0f41acad3 100644
--- a/deeptutor/capabilities/ask_questions/capability.py
+++ b/deeptutor/capabilities/ask_questions/capability.py
@@ -6,29 +6,18 @@ from typing import cast
from deeptutor.agents.chat.agentic_pipeline import AgenticChatPipeline
from 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_manifest
from deeptutor.runtime.stream_bus import StreamBus
class 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"] = True
diff --git a/deeptutor/capabilities/audio_overview/capability.py b/deeptutor/capabilities/audio_overview/capability.py
index 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, TurnCapability
from deeptutor.core.context import UnifiedContext
from deeptutor.i18n import StatusI18n
-from deeptutor.runtime.request_contracts import get_capability_request_schema
+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifest
from deeptutor.runtime.stream_bus import StreamBus
class 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_storage
note = get_co_writer_storage().load_document(note_id)
diff --git a/deeptutor/capabilities/mastery/capability.py b/deeptutor/capabilities/mastery/capability.py
index 76fdae8b3..801a060eb 100644
--- a/deeptutor/capabilities/mastery/capability.py
+++ b/deeptutor/capabilities/mastery/capability.py
@@ -28,14 +28,13 @@ from typing import cast
import uuid
from deeptutor.capabilities.mastery.pipeline import MasteryLoopPipeline
-from deeptutor.capabilities.mastery.tools import MASTERY_TOOL_NAMES
from deeptutor.core.capability_protocol import (
- CapabilityManifest,
StreamBusProtocol,
TurnCapability,
)
from deeptutor.core.context import UnifiedContext
from deeptutor.learning.identity import resolve_mastery_path_binding
+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifest
from 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.py
index 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_NAMES
from deeptutor.core.capability_protocol import (
- CapabilityManifest,
StreamBusProtocol,
TurnCapability,
)
from deeptutor.core.context import UnifiedContext
+from deeptutor.runtime.bootstrap.builtin_capabilities import builtin_capability_manifest
from deeptutor.runtime.stream_bus import StreamBus
class 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 loop
diff --git a/deeptutor/capabilities/registry.py b/deeptutor/capabilities/registry.py
index e35aa8879..ace540054 100644
--- a/deeptutor/capabilities/registry.py
+++ b/deeptutor/capabilities/registry.py
@@ -13,6 +13,7 @@ import warnings
from deeptutor.capabilities.protocol import LoopExtension
from deeptutor.core.context import UnifiedContext
+from deeptutor.modules.catalog import contribution_enabled, manifests
from deeptutor.plugins.entry_points import load_entry_point_group
from 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.py
index 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_id
from deeptutor.multi_user.context import get_current_user
- from deeptutor.services.partners.scope import is_partner_user_id
return bool(is_partner_user_id(get_current_user().id))
except Exception: # noqa: BLE001 - no multi-user layer configured
diff --git a/deeptutor/capabilities/solve/capability.py b/deeptutor/capabilities/solve/capability.py
index 506c6224e..74845dc14 100644
--- a/deeptutor/capabilities/solve/capability.py
+++ b/deeptutor/capabilities/solve/capability.py
@@ -24,14 +24,12 @@ from typing import cast
from deeptutor.agents.chat.agentic_pipeline import AgenticChatPipeline
from deeptutor.capabilities.solve.session import DEFAULT_MAX_REPLANS
-from deeptutor.capabilities.solve.tools import SOLVE_TOOL_NAMES
from 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_manifest
from deeptutor.runtime.stream_bus import StreamBus
from 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"] = True
diff --git a/deeptutor/capabilities/subagent/binding.py b/deeptutor/capabilities/subagent/binding.py
index 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.py
index 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 running
diff --git a/deeptutor/core/errors.py b/deeptutor/core/errors.py
index 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 = detail
diff --git a/deeptutor/core/identities.py b/deeptutor/core/identities.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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 FileTypeRouter
from deeptutor.services.rag.index_probe import provider_failure_summary
from deeptutor.services.rag.index_versioning import list_kb_versions
from 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 FileTypeRouter
logger = logging.getLogger(__name__)
diff --git a/deeptutor/knowledge/indexing_run.py b/deeptutor/knowledge/indexing_run.py
index 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 annotations
import asyncio
-from contextvars import ContextVar
from hashlib import sha256
import json
import os
from pathlib import Path
-import re
import sys
import threading
import time
@@ -26,8 +24,22 @@ except ImportError: # CLI-only installs need no process-monitor dependency.
psutil = None
from 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 FileTypeRouter
candidates = list(dict.fromkeys(self.sources))
raw = self.kb_dir / "raw"
diff --git a/deeptutor/knowledge/initializer.py b/deeptutor/knowledge/initializer.py
index 364bd2ba3..cb4fb367f 100644
--- a/deeptutor/knowledge/initializer.py
+++ b/deeptutor/knowledge/initializer.py
@@ -21,13 +21,13 @@ from deeptutor.knowledge.progress_tracker import ProgressStage, ProgressTracker
from deeptutor.services.config import resolve_llm_runtime_config
from deeptutor.services.file_io import atomic_write_json
from deeptutor.services.rag.factory import normalize_provider_name
-from deeptutor.services.rag.file_routing import FileTypeRouter
from deeptutor.services.rag.service import RAGService
from deeptutor.services.setup.data_volume import (
DataVolumePermissionError,
ensure_data_volume_writable,
format_data_volume_permission_error,
)
+from deeptutor.utils.file_types import FileTypeRouter
logger = logging.getLogger(__name__)
diff --git a/deeptutor/knowledge/manager.py b/deeptutor/knowledge/manager.py
index 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 FileTypeRouter
from 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 FileTypeRouter
logger = logging.getLogger(__name__)
diff --git a/deeptutor/knowledge/module_service.py b/deeptutor/knowledge/module_service.py
new file mode 100644
index 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.py
index 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[TopicM
the reason — because "this chapter exists but has not been written" is
something 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_context
from deeptutor.book.storage import get_book_storage
@@ -199,6 +202,9 @@ def _load_book_materials(source_id: str, label: str, budget: int) -> list[TopicM
def _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_manager
records = get_notebook_manager().get_records_by_references(
@@ -345,6 +351,9 @@ def _load_question_bank_material(source_id: str, label: str, budget: int) -> Top
def _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_storage
document = get_co_writer_storage().load_document(source_id)
diff --git a/deeptutor/modules/__init__.py b/deeptutor/modules/__init__.py
new file mode 100644
index 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.py
new file mode 100644
index 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 rows
diff --git a/deeptutor/modules/lifecycle.py b/deeptutor/modules/lifecycle.py
new file mode 100644
index 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 stdout
diff --git a/deeptutor/modules/manifests/audio-overview.json b/deeptutor/modules/manifests/audio-overview.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.json
new file mode 100644
index 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.py
new file mode 100644
index 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 callbacks
diff --git a/deeptutor/multi_user/knowledge_access.py b/deeptutor/multi_user/knowledge_access.py
index 83e67a2fd..bb4c84a49 100644
--- a/deeptutor/multi_user/knowledge_access.py
+++ b/deeptutor/multi_user/knowledge_access.py
@@ -4,12 +4,13 @@ from __future__ import annotations
from functools import lru_cache
from 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 AccessError
from deeptutor.knowledge.kb_types import SUBAGENT_KB_TYPE
-from deeptutor.knowledge.manager import KnowledgeBaseManager
from 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) -> KnowledgeResourc
if 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) -> KnowledgeResourc
if 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) -> KnowledgeResourc
read_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 None
try:
resource = resolve_kb(str(kb_ref), require_write=False)
- except HTTPException:
+ except AccessError:
return None
manager = _manager_for(str(resource.base_dir.resolve()))
return manager.get_metadata(resource.name)
@@ -385,7 +391,7 @@ def resolve_kb_manifest(
return None
try:
resource = resolve_kb(str(kb_ref), require_write=False)
- except HTTPException:
+ except AccessError:
return None
manager = _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 None
try:
resource = resolve_kb(str(kb_ref), require_write=False)
- except HTTPException:
+ except AccessError:
return None
manager = _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.py
index 7966c0cae..5c0bc60fd 100644
--- a/deeptutor/multi_user/partner_access.py
+++ b/deeptutor/multi_user/partner_access.py
@@ -25,7 +25,7 @@ from __future__ import annotations
from typing import Any
-from fastapi import HTTPException
+from deeptutor.core.errors import AccessError
from .context import get_current_user
from .grants import load_grant
@@ -88,7 +88,7 @@ def assert_partner_allowed(partner_id: str, user_id: str | None = None) -> None:
return
if 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.py
index 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 privileged
account there is).
"""
- from deeptutor.services.partners.scope import is_partner_user_id
+ from deeptutor.core.identities import is_partner_user_id
from .context import get_current_user_or_none
diff --git a/deeptutor/multi_user/skill_access.py b/deeptutor/multi_user/skill_access.py
index 91318122c..598c6c6bb 100644
--- a/deeptutor/multi_user/skill_access.py
+++ b/deeptutor/multi_user/skill_access.py
@@ -4,8 +4,6 @@ from __future__ import annotations
from typing import Any
-from fastapi import HTTPException
-
from .context import get_current_user
from .grants import load_grant
@@ -71,4 +69,6 @@ def assert_skill_allowed(name: str) -> None:
if user.is_admin:
return
if 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.py
index 67cfa47a7..3d6f68e9c 100644
--- a/deeptutor/partners/helpers.py
+++ b/deeptutor/partners/helpers.py
@@ -4,6 +4,8 @@ from datetime import datetime
from pathlib import Path
import 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.py
index ad5dbf22f..2082dc713 100644
--- a/deeptutor/plugins/runtime.py
+++ b/deeptutor/plugins/runtime.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import asyncio
+from contextvars import ContextVar
from dataclasses import asdict, dataclass
import json
import logging
@@ -10,6 +11,8 @@ import os
from pathlib import Path
import re
import subprocess
+import threading
+import time
from typing import Any, Mapping
from 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._definition
async 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 signal
import threading
from 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:
+ continue
except BaseException:
stop()
process.wait(timeout=3)
diff --git a/deeptutor/runtime/bootstrap/builtin_capabilities.py b/deeptutor/runtime/bootstrap/builtin_capabilities.py
index 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 annotations
from dataclasses import dataclass
from 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.py
index 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.py
index 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 annotations
import 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.py
index 9ed3b7798..2f4f9faaa 100644
--- a/deeptutor/runtime/registry/capability_registry.py
+++ b/deeptutor/runtime/registry/capability_registry.py
@@ -12,6 +12,7 @@ from pydantic import BaseModel
from deeptutor.core.capability_protocol import TurnCapability
from deeptutor.i18n.metadata_i18n import capability_description_i18n
+from deeptutor.modules.catalog import contribution_enabled
from deeptutor.plugins.entry_points import load_entry_point_group
from deeptutor.runtime.bootstrap.builtin_capabilities import BUILTIN_CAPABILITY_SPECS
from 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):
+ continue
if self.catalog.get("turn", name) is not None:
continue
class_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 None
if name not in BUILTIN_CAPABILITY_SPECS:
from deeptutor.plugins.registry import PluginRegistry
from 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_records
diff --git a/deeptutor/runtime/registry/tool_registry.py b/deeptutor/runtime/registry/tool_registry.py
index 6537eacd2..c6cc92a35 100644
--- a/deeptutor/runtime/registry/tool_registry.py
+++ b/deeptutor/runtime/registry/tool_registry.py
@@ -13,6 +13,7 @@ import logging
from typing import Any
from deeptutor.core.tool_protocol import BaseTool, ToolDefinition, ToolPromptHints
+from deeptutor.modules.catalog import contribution_enabled
from deeptutor.plugins.entry_points import load_entry_point_group
from 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 None
return 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.py
index 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, Literal
from 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, manifests
from 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.py
index 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_enabled
from deeptutor.services.cron.service import compute_next_run, get_cron_service
from deeptutor.services.practice.storage import _DUE_AT_SQL, PracticeStore
from 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 += 1
practice = 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__.py
index 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_settings
from .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.py
index 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_enabled
from deeptutor.multi_user.knowledge_access import current_kb_manager
from 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_preflight
from 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 None
knowledge_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_scope
from deeptutor.services.rag.embedding_binding import binding_status
+ from deeptutor.services.rag.preflight import engine_preflight
binding_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.py
index 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 the
engine does not exist.
"""
+ from deeptutor.modules.catalog import module_enabled
+
+ if not module_enabled("parsing"):
+ return ()
from deeptutor.services.parsing.engines._install import installable_engines
from 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_available
if is_engine_available(value):
diff --git a/deeptutor/services/cron/executor.py b/deeptutor/services/cron/executor.py
index 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 InboundMessage
from deeptutor.services.partners import get_partner_manager
diff --git a/deeptutor/services/cron/module_service.py b/deeptutor/services/cron/module_service.py
new file mode 100644
index 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.py
index 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_service
data_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_service
diff --git a/deeptutor/services/parsing/engines/_install.py b/deeptutor/services/parsing/engines/_install.py
index 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 = False
def 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.py
index 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 parser
def 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 False
loader = _ENGINE_LOADERS.get(_normalize_name(name))
if loader is None:
return False
diff --git a/deeptutor/services/parsing/engines/mineru/local.py b/deeptutor/services/parsing/engines/mineru/local.py
index 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_run
run = current_run()
started = activity = time.monotonic()
diff --git a/deeptutor/services/parsing/progress.py b/deeptutor/services/parsing/progress.py
new file mode 100644
index 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.py
index 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_code
run = current_run()
source = Path(source_path)
@@ -189,7 +189,7 @@ class ParseService:
markdown, blocks, asset_dir = "", None, None
if 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_run
if 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.py
new file mode 100644
index 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.py
index 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_id
from deeptutor.multi_user.models import CurrentUser, UserScope
from 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.py
index 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_kb
from deeptutor.knowledge.manager import KnowledgeBaseManager
from deeptutor.multi_user.knowledge_access import resolve_kb
diff --git a/deeptutor/services/rag/file_routing.py b/deeptutor/services/rag/file_routing.py
index 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.py
index b994b559a..340ec09d8 100644
--- a/deeptutor/services/rag/pipelines/graphrag/ingestion.py
+++ b/deeptutor/services/rag/pipelines/graphrag/ingestion.py
@@ -17,7 +17,7 @@ import logging
from pathlib import Path
from typing import Iterable
-from deeptutor.services.rag.file_routing import FileTypeRouter
+from deeptutor.utils.file_types import FileTypeRouter
from . import storage
diff --git a/deeptutor/services/rag/pipelines/llamaindex/document_loader.py b/deeptutor/services/rag/pipelines/llamaindex/document_loader.py
index 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_client
from deeptutor.services.llm.image_caption_batch import ImageCaptionBatcher
from deeptutor.services.llm.image_caption_cache import complete_image_caption
from deeptutor.services.llm.image_description import get_image_description_client
-from deeptutor.services.rag.file_routing import FileTypeRouter
from deeptutor.services.rag.source_pages import SourcePageError
from deeptutor.services.rag.visual_assets import VisualAssetCandidate, collect_visual_assets
from deeptutor.utils.document_validator import DocumentValidator
+from deeptutor.utils.file_types import FileTypeRouter
from .config import image_description_batch_size, image_description_limits
diff --git a/deeptutor/services/session/_turn_runtime_shared.py b/deeptutor/services/session/_turn_runtime_shared.py
index 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_references
return normalize_reading_references(value)
diff --git a/deeptutor/services/session/attachment_parsing.py b/deeptutor/services/session/attachment_parsing.py
index 201838938..00d7c98c4 100644
--- a/deeptutor/services/session/attachment_parsing.py
+++ b/deeptutor/services/session/attachment_parsing.py
@@ -9,7 +9,6 @@ import re
from typing import Any
from deeptutor.services.config.runtime_settings import get_chat_attachment_limits
-from deeptutor.services.parsing import get_parse_service
from deeptutor.services.storage import AttachmentStore
from 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.py
index 01bd1d7f9..bac015fac 100644
--- a/deeptutor/services/session/source_inventory.py
+++ b/deeptutor/services/session/source_inventory.py
@@ -34,7 +34,6 @@ import hashlib
import logging
from typing import Any, Sequence
-from deeptutor.reading.references import resolve_reading_sources
from deeptutor.services.session.protocol import SessionStoreProtocol
logger = 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_context
try:
diff --git a/deeptutor/services/session/turns/executor.py b/deeptutor/services/session/turns/executor.py
index 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_context
from deeptutor.core.context import Attachment, TurnRuntimeContext, UnifiedContext
+ from deeptutor.core.source_context import SourceContext
+ from deeptutor.modules.catalog import require_module
from deeptutor.services.learning_journal import get_learning_journal_store
- from deeptutor.services.memory import get_memory_store
from 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_manager
from deeptutor.services.workspace import get_content_workspace_service
request_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.references
reading_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_context
workspace_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_block
zh = 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.py
index 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_id
from deeptutor.multi_user.context import get_current_user
- from deeptutor.services.partners.scope import is_partner_user_id
from deeptutor.services.workspace import get_content_workspace_service
from 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.py
index 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_id
from deeptutor.multi_user.context import get_current_user
- from deeptutor.services.partners.scope import is_partner_user_id
from deeptutor.services.workspace import get_content_workspace_service
root = (
diff --git a/deeptutor/services/storage/attachment_store.py b/deeptutor/services/storage/attachment_store.py
index 1add9469b..696b5e90c 100644
--- a/deeptutor/services/storage/attachment_store.py
+++ b/deeptutor/services/storage/attachment_store.py
@@ -36,9 +36,9 @@ import shutil
from typing import Protocol, runtime_checkable
from urllib.parse import quote
-from deeptutor.partners.helpers import safe_filename
from deeptutor.services.config import load_system_settings
from deeptutor.services.path_service import get_path_service
+from deeptutor.utils.filenames import safe_filename
logger = logging.getLogger(__name__)
diff --git a/deeptutor/services/suggestions.py b/deeptutor/services/suggestions.py
index 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 here
would 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_store
try:
@@ -382,6 +386,10 @@ def _collect_material(trace_count: int) -> _Material:
what they are in the middle of, and which surface it happened on says
nothing about that.
"""
+ from deeptutor.modules.catalog import module_enabled
+
+ if not module_enabled("memory"):
+ return _Material(profile="", topics=[])
from deeptutor.services.memory import recall
seen: set[str] = set()
diff --git a/deeptutor/services/web_source/sync.py b/deeptutor/services/web_source/sync.py
index 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 FileTypeRouter
from deeptutor.services.rag.service import RAGService
+ from deeptutor.utils.file_types import FileTypeRouter
files = FileTypeRouter.collect_supported_files(raw_dir, recursive=True)
if not files:
diff --git a/deeptutor/services/workspace/knowledge.py b/deeptutor/services/workspace/knowledge.py
index 5c9c84d6b..b623c8fe5 100644
--- a/deeptutor/services/workspace/knowledge.py
+++ b/deeptutor/services/workspace/knowledge.py
@@ -8,7 +8,7 @@ from dataclasses import replace
import json
from pathlib import Path
-from fastapi import HTTPException
+from deeptutor.core.errors import AccessError
library_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 exc
return 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.py
index 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.py
index 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_PREFIX
from deeptutor.multi_user.context import get_current_user_or_none
- from deeptutor.services.partners.scope import PARTNER_USER_PREFIX
user = 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.py
index 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 _token
user = 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.py
index e31f7c3b8..1fa8804a2 100644
--- a/deeptutor/utils/document_extractor.py
+++ b/deeptutor/utils/document_extractor.py
@@ -32,10 +32,6 @@ from typing import Any
from urllib.parse import unquote
import zipfile
-from defusedxml import ElementTree as DefusedElementTree
-from defusedxml.common import DefusedXmlException
-
-from deeptutor.services.rag.file_routing import FileTypeRouter
from 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 FileTypeRouter
logger = 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.py
index 2a10969d0..8e8353a9b 100644
--- a/deeptutor/utils/document_images.py
+++ b/deeptutor/utils/document_images.py
@@ -34,8 +34,6 @@ import re
from typing import Any
import 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 cleaned
diff --git a/deeptutor_cli/main.py b/deeptutor_cli/main.py
index 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_module
from pathlib import Path
import sys
import typer
from deeptutor.logging import configure_logging
+from deeptutor.modules.catalog import manifests, module_enabled
from deeptutor.runtime.mode import RunMode, set_mode
-from .book import register as register_book
from .chat import register as register_chat
from .common import build_turn_request, console, maybe_run
from .config_cmd import register as register_config
from .doctor import register as register_doctor
from .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_module
from .plugin import register as register_plugin
from .provider_cmd import register as register_provider
from .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_web
start_web(home=home, dev=dev, detach=detach, open_browser=open_browser)
@@ -171,6 +170,9 @@ def serve(
import asyncio
import 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.py
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.py
index 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.toml
index 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.toml
index 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 = true
diff --git a/requirements.txt b/requirements.txt
index 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.txt
diff --git a/requirements/cli.txt b/requirements/cli.txt
index 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.txt
diff --git a/requirements/core.txt b/requirements/core.txt
new file mode 100644
index 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.0
diff --git a/requirements/full.txt b/requirements/full.txt
new file mode 100644
index 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.txt
diff --git a/requirements/modules/audio-overview.txt b/requirements/modules/audio-overview.txt
new file mode 100644
index 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.txt
diff --git a/requirements/modules/books.txt b/requirements/modules/books.txt
new file mode 100644
index 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.txt
diff --git a/requirements/modules/calendar.txt b/requirements/modules/calendar.txt
new file mode 100644
index 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.0
diff --git a/requirements/modules/co-writer.txt b/requirements/modules/co-writer.txt
new file mode 100644
index 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.txt
diff --git a/requirements/modules/knowledge.txt b/requirements/modules/knowledge.txt
new file mode 100644
index 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.0
diff --git a/requirements/modules/mastery.txt b/requirements/modules/mastery.txt
new file mode 100644
index 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.txt
diff --git a/requirements/modules/memory.txt b/requirements/modules/memory.txt
new file mode 100644
index 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.txt
diff --git a/requirements/modules/notebook.txt b/requirements/modules/notebook.txt
new file mode 100644
index 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.txt
diff --git a/requirements/modules/parser-docling.txt b/requirements/modules/parser-docling.txt
new file mode 100644
index 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.1
diff --git a/requirements/modules/parser-liteparse.txt b/requirements/modules/parser-liteparse.txt
new file mode 100644
index 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.2
diff --git a/requirements/modules/parser-markitdown.txt b/requirements/modules/parser-markitdown.txt
new file mode 100644
index 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.7
diff --git a/requirements/modules/parser-pymupdf4llm.txt b/requirements/modules/parser-pymupdf4llm.txt
new file mode 100644
index 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.2
diff --git a/requirements/modules/parsing.txt b/requirements/modules/parsing.txt
new file mode 100644
index 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.txt
new file mode 100644
index 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.0
diff --git a/requirements/modules/providers.txt b/requirements/modules/providers.txt
new file mode 100644
index 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.1
diff --git a/requirements/modules/questions.txt b/requirements/modules/questions.txt
new file mode 100644
index 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.txt
diff --git a/requirements/modules/reading.txt b/requirements/modules/reading.txt
new file mode 100644
index 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.0
diff --git a/requirements/modules/renderer-manim.txt b/requirements/modules/renderer-manim.txt
new file mode 100644
index 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.0
diff --git a/requirements/modules/research.txt b/requirements/modules/research.txt
new file mode 100644
index 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.0
diff --git a/requirements/modules/server.txt b/requirements/modules/server.txt
new file mode 100644
index 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.0
diff --git a/requirements/modules/solve.txt b/requirements/modules/solve.txt
new file mode 100644
index 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.txt
diff --git a/requirements/modules/video-lesson.txt b/requirements/modules/video-lesson.txt
new file mode 100644
index 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.txt
diff --git a/requirements/modules/visualize.txt b/requirements/modules/visualize.txt
new file mode 100644
index 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.txt
diff --git a/requirements/modules/web.txt b/requirements/modules/web.txt
new file mode 100644
index 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.txt
diff --git a/requirements/server.txt b/requirements/server.txt
index 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.txt
diff --git a/scripts/build_modules.py b/scripts/build_modules.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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 DeepTutorApp
monkeypatch.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.py
index 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, mo
attachments = 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.py
index 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.py
index 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 PathService
from 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: board
diff --git a/tests/app/test_capability_contracts.py b/tests/app/test_capability_contracts.py
index 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.py
index 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.py
index 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.py
new file mode 100644
index 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.stderr
diff --git a/tests/modules/test_modules.py b/tests/modules/test_modules.py
new file mode 100644
index 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.py
new file mode 100644
index 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 None
diff --git a/tests/modules/test_worker_stream.py b/tests/modules/test_worker_stream.py
new file mode 100644
index 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.py
index 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, monk
def test_legacy_account_selection_redirect_is_private_to_owner(as_user):
- from fastapi import HTTPException
+ from deeptutor.core.errors import AccessError
with 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.py
index 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 annotations
from fastapi import HTTPException
import pytest
+from deeptutor.core.errors import AccessError
from deeptutor.multi_user import partner_access
from 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 == 403
diff --git a/tests/multi_user/test_skill_resolution_scoped.py b/tests/multi_user/test_skill_resolution_scoped.py
index 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 annotations
from fastapi import HTTPException
import pytest
+from deeptutor.core.errors import AccessError
from deeptutor.multi_user import grants as grants_mod
from 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 == 403
diff --git a/tests/multi_user/test_workspace_resources.py b/tests/multi_user/test_workspace_resources.py
index 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 Path
from fastapi import HTTPException
import pytest
+from deeptutor.core.errors import AccessError
from 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_root
assert 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_dir
service.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.py
index 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 _install
manager = _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.py
index 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 SimpleNamespace
import psutil
import pytest
-from deeptutor.knowledge import indexing_run
+from deeptutor.services.parsing import progress
from 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, ex
return 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.py
index 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![figure](image.png)")
- 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="![page](page-1.png)")
- 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.py
index 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 Path
import tomllib
+from packaging.requirements import Requirement
import 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.py
index 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, deployment
assert "openpyxl" in text, deployment
diff --git a/web/components/access/CapabilityGate.tsx b/web/components/access/CapabilityGate.tsx
index 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.tsx
new file mode 100644
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
new file mode 100644
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.ts
new file mode 100644
index 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)
+ })
+})