pyproject.toml

# Python project configuration for DeepTutor
# This file configures Black, Ruff, and other Python tools

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "deeptutor"
dynamic = ["version"]
description = "An agent-native intelligent learning companion with multi-agent collaboration and RAG"
# Python 3.14 is supported by the core app now that compiled base dependencies
# such as FAISS publish compatible wheels. Keep a forward cap so a future
# interpreter is not advertised before the compiled dependency stack is ready.
# Individual optional integrations may carry tighter markers below.
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",
    "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",
    "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",  # 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.
    "mcp>=1.26.0,<2.0.0",
    "pageindex>=0.2.10,<0.3.0",
    # 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.
    "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",
    "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",
    # Process-tree memory readings for /api/system/memory. Soft dependency:
    # deeptutor.runtime.memory_probe imports it lazily and falls back to /proc,
    # so a missing wheel costs the settings strip, not the app.
    "psutil>=5.9.0,<8.0.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 = [
    # 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",
    "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",
    "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.
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"]

# 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",
    "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",
    # weixin QR-code login
    "qrcode>=7.4.0,<9.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]`.
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).
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 rc2 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.7rc2"]

# 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'"]

# 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]",
]

[tool.setuptools]
include-package-data = true

[tool.setuptools.dynamic]
version = {attr = "deeptutor.__version__.__version__"}

[tool.setuptools.packages.find]
where = ["."]
include = ["deeptutor*", "deeptutor_cli*"]

[tool.setuptools.package-data]
# Runtime data shipped inside the deeptutor package: prompt YAMLs (loaded by
# PromptManager from PACKAGE_ROOT/deeptutor/.../prompts/*.yaml), markdown
# templates (builtin SKILL.md files, vision_solver prompts), and helper shell
# scripts. Without these, ``pip install deeptutor`` ships a wheel missing
# every agent prompt and capability fails at first use.
deeptutor = [
    "**/*.yaml",
    "**/*.yml",
    "**/*.md",
    "**/*.json",
    "**/*.sh",
    "**/*.j2",
    "**/*.jinja",
]
deeptutor_cli = ["**/*.md"]
deeptutor_web = ["**/*", ".next/**/*"]

# ============================================
# Black code formatter configuration
# ============================================
[tool.black]
line-length = 100
target-version = ['py311', 'py312', 'py313', 'py314']
include = '\.pyi?$'
extend-exclude = '''
/(
  # Exclude directories
  \.eggs
  | \.git
  | \.hg
  | \.mypy_cache
  | \.tox
  | \.venv
  | venv
  | _build
  | buck-out
  | build
  | dist
  | __pycache__
  | node_modules
  | \.next
)/
'''

# ============================================
# Ruff linter and formatter configuration
# ============================================
[tool.ruff]
# Target Python version
target-version = "py311"
line-length = 100

[tool.ruff.lint]
# Enable only foundational lint rules (intentionally relaxed)
select = [
    "E",   # pycodestyle errors (语法错误)
    "F",   # pyflakes (未使用的导入、变量等)
    "I",   # isort (import 排序)
    # Keep only essential checks; other rules stay relaxed
]

extend-select = [
    "B006",  # Do not use mutable data structures for argument defaults
]

# Ignore specific rules (keep the lint profile relaxed)
ignore = [
    "E501",  # Line too long (handled by formatter)
    "B008",  # Do not perform function calls in argument defaults
    "PLR0911", # Too many return statements
    "PLR0912", # Too many branches
    "PLR0913", # Too many arguments
    "PLR0915", # Too many statements
    "PLR2004", # Magic value used in comparison
    "TRY003", # Avoid specifying long messages outside exception class
    "T201",  # print found (allowed for debugging scripts)
    "E722",  # Do not use bare except (kept relaxed for legacy paths)
    "E402",  # Module level import not at top of file (kept relaxed)
    "PLC0415", # import should be at top-level (kept relaxed)
    "PTH123", # open() should be replaced by Path.open() (standard open allowed)
    "PTH103", # os.makedirs() should be replaced by Path.mkdir() (os.makedirs allowed)
    "PTH118", # os.path.join() should be replaced by Path (os.path.join allowed)
    "EM101",  # Exception must not use a string literal
    "EM102",  # Exception must not use an f-string literal
    "TRY002", # Create your own exception
    "TRY300", # Consider moving this statement to an else block
    "DTZ005", # datetime.now() called without tz argument
    "RET504", # Unnecessary assignment before return
    "PLW2901", # for loop variable overwritten by assignment target
    "F841",  # Local variable assigned but never used
    "ERA001", # Found commented-out code (kept relaxed)
]

# Exclude patterns
exclude = [
    ".bzr",
    ".direnv",
    ".eggs",
    ".git",
    ".git-rewrite",
    ".hg",
    ".mypy_cache",
    ".nox",
    ".pants.d",
    ".pyenv",
    ".pytest_cache",
    ".pytype",
    ".ruff_cache",
    ".svn",
    ".tox",
    ".venv",
    ".vscode",
    "__pypackages__",
    "_build",
    "buck-out",
    "build",
    "dist",
    "node_modules",
    ".next",
    "out",
    "venv",
    "__pycache__",
]

# Allow autofix for all enabled rules
fixable = ["ALL"]
unfixable = []

# Allow unused variables when underscore-prefixed
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"

[tool.ruff.format]
# Use double quotes for strings
quote-style = "double"
# Indent with spaces
indent-style = "space"
# Respect magic trailing comma
skip-magic-trailing-comma = false
# Automatically detect the appropriate line ending
line-ending = "auto"

# ============================================
# Ruff import sorting (isort replacement)
# ============================================
[tool.ruff.lint.isort]
known-first-party = ["deeptutor", "deeptutor_cli", "scripts"]
force-sort-within-sections = true
split-on-trailing-comma = true

# ============================================
# Ruff per-file-ignores
# ============================================
[tool.ruff.lint.per-file-ignores]
# Allow longer lines in test files
# F401: Allow unused imports for availability checks in tests
"**/test_*.py" = ["E501", "PLR2004", "F401"]
"**/__init__.py" = ["F401"]  # Allow unused imports in __init__.py

# ============================================
# Ruff mccabe complexity
# ============================================
[tool.ruff.lint.mccabe]
max-complexity = 10

# ============================================
# Pytest configuration
# ============================================
[tool.pytest.ini_options]
testpaths = ["tests", "deeptutor/learning/tests"]
pythonpath = ["."]
markers = [
    "asyncio: mark async tests that require pytest-asyncio",
    "redis_integration: requires DEEPTUTOR_TEST_REDIS_URL",
]
asyncio_default_fixture_loop_scope = "function"
addopts = [
    "--strict-markers",
    "--strict-config",
    "--disable-warnings",
    "--tb=short",
    "--import-mode=importlib",
]

# ============================================
# MyPy type checking configuration
# ============================================
[tool.mypy]
python_version = "3.11"
# Relaxed type checking for gradual adoption
pretty = false
show_error_context = false
warn_return_any = false
warn_no_return = false
show_error_codes = true
ignore_missing_imports = true
follow_imports = "silent"
# Disable strict checks that generate too many errors
check_untyped_defs = false
disallow_untyped_defs = false
disallow_incomplete_defs = false
no_implicit_optional = false

# Module-specific overrides
[[tool.mypy.overrides]]
module = "tests.*"
ignore_errors = true

[[tool.mypy.overrides]]
module = "deeptutor.tools.*"
ignore_errors = true  # Some tools may have dynamic imports

# ============================================
# Bandit security linting configuration
# ============================================
[tool.bandit]
exclude_dirs = ["tests", "scripts"]
# B101=assert, B311=random, B403/B404=pickle/subprocess imports
# B110=try_except_pass (intentional for non-critical error handling)
# B104=hardcoded_bind_all_interfaces (required for server binding)
# B112=try_except_continue (intentional for iteration)
# B105=hardcoded_password_string (false positive on empty string initialization)
# B301=pickle (used for internal embedding cache, not untrusted data)
# B501=request_with_no_cert_validation (opt-in via env var for dev/testing)
# B603=subprocess_without_shell_equals_true (controlled execution)
# B202=tarfile_unsafe_members (already using safe_members filter)
skips = ["B101", "B311", "B403", "B404", "B110", "B104", "B112", "B105", "B301", "B501", "B603", "B202"]