DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
from __future__ import annotations
from copy import deepcopy
from dataclasses import dataclass
import json
import os
from pathlib import Path
from typing import Any, Callable
from deeptutor.services.file_io import atomic_write_json as _atomic_write_json
from deeptutor.services.path_service import get_path_service
from .image_description import normalize_image_description_model
from .origins import normalize_origins
DEFAULT_SYSTEM_SETTINGS: dict[str, Any] = {
"version": 1,
# About → Updates performs at most one release lookup per process/day.
# Operators may disable even that explicit network boundary for offline or
# audited deployments; DEEPTUTOR_VERSION_CHECK_ENABLED is the deployment
# override for read-only settings volumes.
"version_check_enabled": True,
"backend_port": 8001,
"backend_workers": 1,
"frontend_port": 3782,
"next_public_api_base_external": "",
"next_public_api_base": "",
"cors_origin": "",
"cors_origins": [],
"disable_ssl_verify": False,
"chat_attachment_dir": "",
# Enable the restricted-subprocess code-execution sandbox (the `exec` /
# unified `exec` tool the office skills — docx/pdf/pptx/xlsx — run on).
# Default on so document generation works out of the box across all
# deployment shapes; a stronger backend (runner sidecar / bwrap) still
# takes precedence when available. Set false to disable host-side exec.
"sandbox_allow_subprocess": True,
# Conservative chat -> deep_question routing. Explicit requests only, and
# callers can still pass config.auto_route=false for a single turn.
"capability_routing_enabled": False,
# Reference policy applied after every web-search provider. This belongs in
# runtime JSON so packaged installs and the settings service share one
# source of truth; project main.yaml is intentionally not an operator
# configuration surface.
"web_search_source_filtering": {
"enabled": True,
"blocked_domains": [],
"trusted_domains": [],
"content_filtering": True,
"use_educational_trusted_domains": False,
"use_moderation": False,
},
# Chat attachment policy. Size caps gate what the composer accepts and
# what the turn runtime / partner upload endpoints extract; the char
# budgets bound how much extracted text is inlined into the LLM context
# per document / per turn. Enforcement reads these at call time, so
# changes apply to the next message — but uploads whose base64 payload
# exceeds the WebSocket frame ceiling need a restart (see
# ``compute_ws_max_size``, wired at every uvicorn launch point).
"chat_attachment_max_file_mb": 20,
"chat_attachment_max_total_mb": 25,
"chat_attachment_max_chars_per_doc": 200_000,
"chat_attachment_max_chars_total": 150_000,
# Images the manifest cannot carry across turns are re-attached by the
# turn executor instead (#1438). This bounds how many of a conversation's
# earlier images ride along on every later turn — a re-sent payload, so
# it is a policy like the caps above, not an LLM budget.
"chat_prior_image_reinject_max": 4,
# Opt-in fastapi-guard request screening (deeptutor/api/security_guard.py).
# Off by default: when disabled, the package is never imported and the
# middleware stack is unchanged. ``trusted_proxies`` are the only peers
# whose X-Forwarded-For is believed; an empty list means the socket peer is
# always the client. The rate limit counts every HTTP request from one
# client address, so it is sized for the frontend's polling, not for one
# call per page view.
"security_guard": {
"enabled": False,
"rate_limit": 300,
"rate_limit_window": 60,
"trusted_proxies": ["127.0.0.1", "::1"],
# Skip the rate limit only. The bundled frontend hides browser
# addresses, so its traffic arrives as loopback and would share one
# bucket; loopback requests that carry X-Forwarded-For still resolve
# to, and are limited as, the forwarded client.
"exempt_ips": ["127.0.0.1", "::1"],
"whitelist": [],
"blacklist": [],
},
}
# Clamp bounds for the chat attachment knobs. The MB ceilings are deliberately
# generous (local deployments parse in-process; the WS frame cap is derived
# from the total) while still refusing nonsense like 0 or 10^9.
CHAT_ATTACHMENT_MAX_FILE_MB_RANGE = (1, 1024)
CHAT_ATTACHMENT_MAX_TOTAL_MB_RANGE = (1, 2048)
CHAT_ATTACHMENT_CHARS_RANGE = (10_000, 5_000_000)
# Zero is a real choice here — it turns prior-image re-injection off for a
# deployment whose model or bandwidth cannot afford it.
CHAT_PRIOR_IMAGE_REINJECT_RANGE = (0, 20)
DEFAULT_AUTH_SETTINGS: dict[str, Any] = {
"version": 1,
"enabled": False,
"username": "admin",
"password_hash": "",
"token_expire_hours": 24,
"cookie_secure": False,
"private_login_hosts": [],
}
DEFAULT_INTEGRATIONS_SETTINGS: dict[str, Any] = {
"version": 2,
"pocketbase_url": "",
"pocketbase_port": 8090,
"pocketbase_external_url": "",
"pocketbase_admin_email": "",
"pocketbase_admin_password": "",
"turn_coordination": {
"backend": "memory",
"redis_url": "",
"key_prefix": "deeptutor",
"lease_ttl_seconds": 30,
"renew_interval_seconds": 10,
"recovery_interval_seconds": 10,
"stream_retention_seconds": 86_400,
},
}
# Document parsing settings. The parse layer (deeptutor/services/parsing)
# supports several pluggable engines; one is active at a time. The persisted
# shape is v2::
#
# {"version": 2, "engine": "<name>", "engines": {"text_only": {...},
# "mineru": {...}, "docling": {...}, "markitdown": {...}}}
#
# Persisted as ``document_parsing.json``. It originally held only MinerU config
# and was named ``mineru.json``; the file is renamed in place on first load (see
# ``_migrate_legacy_document_parsing_file``) so existing installs keep their
# settings. ``load_mineru`` returns the MinerU engine *slice* (flat) so legacy
# readers keep working; ``load_document_parsing`` returns the whole structure
# for the multi-engine settings UI. A v1 flat file is migrated into
# ``engines.mineru`` on first load (and the active engine pinned to "mineru" so
# existing installs keep their behavior).
DOCUMENT_PARSING_SETTINGS_NAME = "document_parsing"
_LEGACY_DOCUMENT_PARSING_SETTINGS_NAME = "mineru"
MINERU_MODE_LOCAL = "local"
MINERU_MODE_CLOUD = "cloud"
_MINERU_MODES = frozenset({MINERU_MODE_LOCAL, MINERU_MODE_CLOUD})
DOCLING_MODE_LOCAL = "local"
DOCLING_MODE_REMOTE = "remote"
_DOCLING_MODES = frozenset({DOCLING_MODE_LOCAL, DOCLING_MODE_REMOTE})
_MINERU_MODEL_VERSIONS = frozenset({"pipeline", "vlm"})
_MINERU_DOWNLOAD_SOURCES = frozenset({"huggingface", "modelscope"})
DOCUMENT_PARSING_ENGINE_TEXT_ONLY = "text_only"
DOCUMENT_PARSING_ENGINE_MINERU = "mineru"
DOCUMENT_PARSING_ENGINE_DOCLING = "docling"
DOCUMENT_PARSING_ENGINE_MARKITDOWN = "markitdown"
DOCUMENT_PARSING_ENGINE_PYMUPDF4LLM = "pymupdf4llm"
DOCUMENT_PARSING_ENGINE_LITEPARSE = "liteparse"
DOCUMENT_PARSING_ENGINE_TIKA = "tika"
_DOCUMENT_PARSING_ENGINES = frozenset(
{
DOCUMENT_PARSING_ENGINE_TEXT_ONLY,
DOCUMENT_PARSING_ENGINE_MINERU,
DOCUMENT_PARSING_ENGINE_DOCLING,
DOCUMENT_PARSING_ENGINE_MARKITDOWN,
DOCUMENT_PARSING_ENGINE_PYMUPDF4LLM,
DOCUMENT_PARSING_ENGINE_LITEPARSE,
DOCUMENT_PARSING_ENGINE_TIKA,
}
)
# Image formats PyMuPDF4LLM can write extracted page images as.
_PYMUPDF4LLM_IMAGE_FORMATS = frozenset({"png", "jpg", "jpeg", "webp"})
# How LiteParse presents images in its Markdown. Independent of whether the
# image bytes are extracted (that is the engine's ``extract_images`` knob).
LITEPARSE_IMAGE_MODES = frozenset({"off", "placeholder", "embed"})
# Fresh installs default to the built-in text extractor so parsing works out of
# the box without optional parser packages or model weights.
# Migrated v1 installs keep MinerU (see ``_normalize_document_parsing``).
_DEFAULT_DOCUMENT_PARSING_ENGINE = DOCUMENT_PARSING_ENGINE_TEXT_ONLY
# MinerU engine slice. ``mode`` selects a locally-installed MinerU CLI ("local")
# vs the hosted mineru.net cloud API ("cloud"); cloud needs ``api_token``. Every
# other field is a parsing knob both backends understand. ``allow_local_model_download``
# gates the first-parse model pull (default off → no silent multi-GB download).
_DEFAULT_MINERU_ENGINE: dict[str, Any] = {
"mode": MINERU_MODE_LOCAL,
"api_base_url": "https://mineru.net",
"api_token": "",
# Optional explicit path to a local MinerU executable. Empty = auto-detect
# from PATH. Lets users install MinerU in an isolated env (uv tool / pipx /
# separate conda) so its heavy deps never conflict with DeepTutor's.
"local_cli_path": "",
# Where local-mode model weights download from. ``model_download_endpoint``
# is a custom HuggingFace mirror (HF_ENDPOINT, e.g. https://hf-mirror.com);
# empty = the source's official address.
"model_download_source": "huggingface",
"model_download_endpoint": "",
"model_version": "pipeline",
# "auto" lets MinerU auto-detect; any other value is forwarded verbatim
# as the API ``language`` hint (e.g. "ch", "en").
"language": "auto",
"enable_formula": True,
"enable_table": True,
"is_ocr": False,
"max_pages_per_part": 180,
"normalize_tiny_scans": False,
"allow_local_model_download": False,
}
# Docling engine slice. ``mode`` selects the in-process ``docling`` package
# ("local") or a Docling Serve HTTP server ("remote"; needs ``api_base_url`` and
# optionally ``api_token``). Local downloads layout/table models on first run,
# hence the same ``allow_local_model_download`` gate as MinerU local.
_DEFAULT_DOCLING_ENGINE: dict[str, Any] = {
"mode": DOCLING_MODE_LOCAL,
"api_base_url": "http://localhost:5001",
"api_token": "",
"do_ocr": False,
"do_table_structure": True,
"allow_local_model_download": False,
}
# markitdown engine slice. Pure-Python, no model downloads. Optionally uses
# DeepTutor's VLM to describe images.
_DEFAULT_MARKITDOWN_ENGINE: dict[str, Any] = {
"enable_llm_image_description": False,
}
# PyMuPDF4LLM engine slice. Pure-Python on top of PyMuPDF — no model downloads,
# no CUDA, runs on low-end / GPU-less machines. Unlike text-only/markitdown it
# can also extract embedded images and rendered vector graphics into the parse's
# images/ dir. ``image_dpi`` is the render resolution for those images.
_DEFAULT_PYMUPDF4LLM_ENGINE: dict[str, Any] = {
"write_images": True,
"image_format": "png",
"image_dpi": 150,
}
# LiteParse engine slice. Rust-backed, no model downloads. Like PyMuPDF4LLM it
# can extract embedded images into the parse's images/ dir. Output format and
# image directory are fixed by the workdir contract, so neither is a knob here
# (see engines/liteparse/engine.py). ``max_pages`` 0 means the whole document.
_DEFAULT_LITEPARSE_ENGINE: dict[str, Any] = {
"image_mode": "placeholder",
"extract_links": True,
"extract_images": False,
"max_pages": 0,
}
# Tika engine slice. Remote-only Apache Tika server; no local package or models.
_DEFAULT_TIKA_ENGINE: dict[str, Any] = {
"server_url": "http://localhost:9998",
}
# Built-in text-only engine slice. It deliberately has no knobs: it reuses
# DeepTutor's legacy text extractors for PDF / Office / text-like files.
_DEFAULT_TEXT_ONLY_ENGINE: dict[str, Any] = {}
# Legacy flat keys that mark a v1 ``mineru.json`` (these live only at the top
# level in v1; v2 never writes them there).
_MINERU_ENGINE_KEYS = frozenset(_DEFAULT_MINERU_ENGINE.keys())
DEFAULT_DOCUMENT_PARSING_SETTINGS: dict[str, Any] = {
"version": 2,
"engine": _DEFAULT_DOCUMENT_PARSING_ENGINE,
# Caption embedded figures with a vision model at ingest, so a text-only
# model reading the material can still describe its images.
"image_caption": False,
"image_description_model": None,
"engines": {
DOCUMENT_PARSING_ENGINE_TEXT_ONLY: _DEFAULT_TEXT_ONLY_ENGINE,
DOCUMENT_PARSING_ENGINE_MINERU: _DEFAULT_MINERU_ENGINE,
DOCUMENT_PARSING_ENGINE_DOCLING: _DEFAULT_DOCLING_ENGINE,
DOCUMENT_PARSING_ENGINE_MARKITDOWN: _DEFAULT_MARKITDOWN_ENGINE,
DOCUMENT_PARSING_ENGINE_PYMUPDF4LLM: _DEFAULT_PYMUPDF4LLM_ENGINE,
DOCUMENT_PARSING_ENGINE_LITEPARSE: _DEFAULT_LITEPARSE_ENGINE,
DOCUMENT_PARSING_ENGINE_TIKA: _DEFAULT_TIKA_ENGINE,
},
}
# Backward-compatible alias: the MinerU engine slice. Several call-sites and
# tests reference ``DEFAULT_MINERU_SETTINGS``; it now denotes the engine slice.
DEFAULT_MINERU_SETTINGS: dict[str, Any] = _DEFAULT_MINERU_ENGINE
# PageIndex cloud RAG engine. A KB indexed with the ``pageindex`` provider
# ships its documents to the hosted PageIndex service for tree building and
# reasoning-based retrieval. The SDK owns the official endpoint; the same
# deployment-level credential is reused by every ``pageindex`` KB.
# Kept in its own JSON file so the credential lives beside other per-feature
# settings and never leaks into model/network config.
DEFAULT_PAGEINDEX_SETTINGS: dict[str, Any] = {
"version": 1,
"api_key": "",
}
# Query-rewrite layer for retrieval (``RAGService.search``). Disabled by
# default so behaviour is unchanged until an operator opts in; ``strategy``
# reserves the ``multi_query`` slot for a follow-up PR.
DEFAULT_QUERY_REWRITE_SETTINGS: dict[str, Any] = {
"version": 1,
"enabled": False,
"strategy": "standalone",
"model": "",
"timeout_seconds": 5.0,
"min_query_chars": 12,
}
#: Strategies the query-rewrite layer accepts.
QUERY_REWRITE_STRATEGIES = ("off", "standalone")
# Tencent IMA. The credential pair (``client_id`` + ``api_key``, issued at
# https://ima.qq.com/agent-interface) identifies one IMA account, and every
# library in that account is reachable with it — so it belongs here, beside the
# other engine credentials, rather than being retyped for each connected KB.
# A KB may still carry its own pair to reach a *different* IMA account; that
# per-KB binding wins (see ``pipelines/ima/config.py``).
DEFAULT_IMA_SETTINGS: dict[str, Any] = {
"version": 1,
"client_id": "",
"api_key": "",
}
# LlamaIndex local RAG engine. These are the retrieval + chunking knobs the
# default engine exposes; they were previously hardcoded / env-only. Kept in
# their own JSON file so the engine's detail page can read/write them.
#
# * ``retrieval_profile`` — "hybrid" (BM25 + vector fusion) or "vector" only.
# * ``top_k`` — default number of chunks a query returns.
# * ``vector_top_k_multiplier`` / ``bm25_top_k_multiplier`` — how many extra
# candidates each child retriever fetches before fusion re-ranks to ``top_k``.
# * ``reranker_model`` / ``rerank_top_k`` — optional cross-encoder refinement.
# An empty model keeps the existing embedding-only ranking.
# * ``vector_index_type`` — FAISS index type for the next full index build.
# HNSW is opt-in and trades exact recall for sub-linear search at scale.
# * ``chunk_size`` / ``chunk_overlap`` — indexing chunk geometry; changes apply
# on the next (re-)index, not retroactively.
# * ``image_description_concurrency`` / ``image_description_timeout_seconds`` —
# bounded multimodal LLM work while indexing image-heavy documents.
#
# ``fusion_num_queries`` is intentionally NOT exposed: query generation needs a
# real LLM, but the fusion retriever runs on a MockLLM, so any value > 1 would
# silently degrade results. It stays pinned to the dataclass default.
LLAMAINDEX_VECTOR_PROFILE = "vector"
LLAMAINDEX_HYBRID_PROFILE = "hybrid"
_LLAMAINDEX_PROFILES = frozenset({LLAMAINDEX_VECTOR_PROFILE, LLAMAINDEX_HYBRID_PROFILE})
LLAMAINDEX_FLAT_VECTOR_INDEX = "flat"
LLAMAINDEX_HNSW_VECTOR_INDEX = "hnsw"
_LLAMAINDEX_VECTOR_INDEX_TYPES = frozenset(
{LLAMAINDEX_FLAT_VECTOR_INDEX, LLAMAINDEX_HNSW_VECTOR_INDEX}
)
DEFAULT_LLAMAINDEX_SETTINGS: dict[str, Any] = {
"version": 1,
"retrieval_profile": LLAMAINDEX_HYBRID_PROFILE,
"top_k": 5,
"vector_top_k_multiplier": 2,
"bm25_top_k_multiplier": 2,
"reranker_model": "",
"rerank_top_k": 50,
"vector_index_type": LLAMAINDEX_FLAT_VECTOR_INDEX,
"hnsw_m": 32,
"hnsw_ef_construction": 200,
"hnsw_ef_search": 64,
"chunk_size": 512,
"chunk_overlap": 50,
"image_description_concurrency": 4,
"image_description_batch_size": 1,
"image_description_timeout_seconds": 60,
}
# GraphRAG retrieval knobs (microsoft/graphrag). Only query-time params that the
# engine passes explicitly (engine.py) are exposed; indexing knobs are left to
# GraphRAG's auto-config on purpose (the settings.yaml bridge is deliberately
# minimal). ``response_type`` is a free-form GraphRAG answer style; the UI offers
# presets but any string is accepted. ``community_level`` controls graph
# traversal granularity (local/drift). ``dynamic_community_selection`` only
# affects global search.
DEFAULT_GRAPHRAG_SETTINGS: dict[str, Any] = {
"version": 1,
"response_type": "Multiple Paragraphs",
"community_level": 2,
"dynamic_community_selection": False,
}
# LightRAG retrieval + indexing knobs (HKUDS/LightRAG native SDK). ``top_k``
# is the number of entities/relations the query pulls; ``response_type`` mirrors
# GraphRAG's. These ride into ``QueryParam`` and the pinned SDK constructor.
# ``max_concurrent_files`` sizes the native parser worker pool after DeepTutor
# has frozen each ParseService result; pre-parsing itself remains serial.
# Stable catalog references let LightRAG use a dedicated LLM while the global
# active chat model remains unchanged for ordinary chat.
DEFAULT_LIGHTRAG_SETTINGS: dict[str, Any] = {
"version": 2,
"top_k": 60,
"response_type": "Multiple Paragraphs",
"max_concurrent_files": 1,
"llm_model_max_async": 4,
"entity_extract_max_gleaning": 1,
# Maps to LightRAG's ``default_llm_timeout`` (seconds). LightRAG derives its
# worker execution cap as 2x this value, so 240 -> a 480s per-call ceiling.
"llm_timeout": 240,
"llm_profile_id": "",
"llm_model_id": "",
}
# LightRAG Server connection defaults. Individual knowledge bases remain free
# to override the URL/key when they are connected; this account-level slice is
# the reusable starting point shown on the engine page and in the create flow.
DEFAULT_LIGHTRAG_SERVER_SETTINGS: dict[str, Any] = {
"version": 1,
"server_url": "",
"api_key": "",
}
IGNORE_PROCESS_OVERRIDES_ENV = "DEEPTUTOR_IGNORE_PROCESS_ENV_OVERRIDES"
# Names of the variables a parent DeepTutor process rendered out of the settings
# files, handed to its children so they can tell "our own launcher derived this
# from system.json" from "an operator set this in the deployment". Without it the
# launcher's export looks like a deployment override to the backend and the file
# can never win again: toggling "check for updates" wrote system.json while the
# live API kept answering with the value captured at startup (#1536).
SETTINGS_DERIVED_ENV_KEYS = "DEEPTUTOR_SETTINGS_DERIVED_ENV_KEYS"
# (process env name, security_guard key) deployment overrides.
_SECURITY_GUARD_ENV_KEYS = (
("DEEPTUTOR_GUARD_ENABLED", "enabled"),
("DEEPTUTOR_GUARD_RATE_LIMIT", "rate_limit"),
("DEEPTUTOR_GUARD_RATE_LIMIT_WINDOW", "rate_limit_window"),
("DEEPTUTOR_GUARD_TRUSTED_PROXIES", "trusted_proxies"),
("DEEPTUTOR_GUARD_EXEMPT_IPS", "exempt_ips"),
("DEEPTUTOR_GUARD_WHITELIST", "whitelist"),
("DEEPTUTOR_GUARD_BLACKLIST", "blacklist"),
)
TRUTHY = {"1", "true", "yes", "on"}
FALSY = {"0", "false", "no", "off"}
def _coerce_bool(value: Any, default: bool = False) -> bool:
if isinstance(value, bool):
return value
text = str(value).strip().lower()
if text in TRUTHY:
return True
if text in FALSY:
return False
return default
def _coerce_int(value: Any, default: int) -> int:
try:
return int(str(value).strip())
except (TypeError, ValueError):
return default
def _coerce_clamped_int(value: Any, default: int, low: int, high: int) -> int:
coerced = _coerce_int(value, default)
return max(low, min(high, coerced))
def _coerce_port(value: Any, default: int) -> int:
port = _coerce_int(value, default)
return port if 1 <= port <= 65535 else default
def _coerce_origins(value: Any) -> list[str]:
return normalize_origins(value)
def _deepcopy_default(defaults: dict[str, Any]) -> dict[str, Any]:
return deepcopy(defaults)
def _json_object(path: Path) -> dict[str, Any]:
if not path.exists() or path.stat().st_size == 0:
return {}
try:
loaded = json.loads(path.read_text(encoding="utf-8"))
except Exception:
return {}
return loaded if isinstance(loaded, dict) else {}
def _string(value: Any) -> str:
return "" if value is None else str(value).strip()
def _host_list(value: Any) -> list[str]:
if isinstance(value, list):
return [item for raw in value if (item := _string(raw).lower().rstrip("."))]
raw = _string(value)
return [
item
for piece in raw.replace(";", ",").split(",")
if (item := piece.strip().lower().rstrip("."))
]
def _string_or_list(value: Any) -> str | list[str]:
if isinstance(value, list):
return [item for raw in value if (item := _string(raw))]
return _string(value)
class RuntimeSettingsService:
"""JSON-backed runtime settings rooted in data/user/settings.
Process environment values are explicit deployment overrides and are applied
centrally here rather than scattered through the application. Project-root
``.env`` files are intentionally ignored.
"""
_instances: dict[str, "RuntimeSettingsService"] = {}
def __init__(
self,
settings_dir: Path,
*,
process_env: dict[str, str] | None = None,
) -> None:
self.settings_dir = settings_dir
self.process_env = process_env if process_env is not None else os.environ
self._external_process_keys: set[str] = set()
self._internal_exported_values: dict[str, str] = {}
derived = self.process_env.get(SETTINGS_DERIVED_ENV_KEYS, "") or ""
self._settings_derived_keys: frozenset[str] = frozenset(
part.strip() for part in derived.split(",") if part.strip()
)
@classmethod
def get_instance(
cls,
settings_dir: Path | None = None,
*,
process_env: dict[str, str] | None = None,
) -> "RuntimeSettingsService":
resolved = (settings_dir or _global_settings_dir()).resolve()
key = str(resolved)
if process_env is not None:
return cls(resolved, process_env=process_env)
if key not in cls._instances:
cls._instances[key] = cls(resolved)
return cls._instances[key]
def path_for(self, name: str) -> Path:
if not name.endswith(".json"):
name = f"{name}.json"
return self.settings_dir / name
def load_system(self, *, include_process_overrides: bool = True) -> dict[str, Any]:
payload = self._load_or_create(
"system",
DEFAULT_SYSTEM_SETTINGS,
self._normalize_system,
)
if include_process_overrides:
payload = self._apply_system_process_overrides(payload)
return payload
def save_system(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = self._normalize_system({**DEFAULT_SYSTEM_SETTINGS, **settings})
_atomic_write_json(self.path_for("system"), payload)
return payload
def load_auth(self, *, include_process_overrides: bool = True) -> dict[str, Any]:
payload = self._load_or_create(
"auth",
DEFAULT_AUTH_SETTINGS,
self._normalize_auth,
)
if include_process_overrides:
payload = self._apply_auth_process_overrides(payload)
return payload
def save_auth(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = self._normalize_auth({**DEFAULT_AUTH_SETTINGS, **settings})
_atomic_write_json(self.path_for("auth"), payload)
return payload
def load_integrations(self, *, include_process_overrides: bool = True) -> dict[str, Any]:
payload = self._load_or_create(
"integrations",
DEFAULT_INTEGRATIONS_SETTINGS,
self._normalize_integrations,
)
if include_process_overrides:
payload = self._apply_integrations_process_overrides(payload)
return payload
def save_integrations(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = self._normalize_integrations({**DEFAULT_INTEGRATIONS_SETTINGS, **settings})
_atomic_write_json(self.path_for("integrations"), payload)
return payload
def load_document_parsing(self, *, include_process_overrides: bool = True) -> dict[str, Any]:
"""Return the full v2 document-parsing structure (all engines)."""
self._migrate_legacy_document_parsing_file()
payload = self._load_or_create(
DOCUMENT_PARSING_SETTINGS_NAME,
DEFAULT_DOCUMENT_PARSING_SETTINGS,
self._normalize_document_parsing,
)
if include_process_overrides:
engines = dict(payload["engines"])
engines[DOCUMENT_PARSING_ENGINE_MINERU] = self._apply_mineru_process_overrides(
dict(engines[DOCUMENT_PARSING_ENGINE_MINERU])
)
engines[DOCUMENT_PARSING_ENGINE_DOCLING] = self._apply_docling_process_overrides(
dict(engines[DOCUMENT_PARSING_ENGINE_DOCLING])
)
engines[DOCUMENT_PARSING_ENGINE_TIKA] = self._apply_tika_process_overrides(
dict(engines[DOCUMENT_PARSING_ENGINE_TIKA])
)
payload = {**payload, "engines": engines}
return payload
def save_document_parsing(self, settings: dict[str, Any]) -> dict[str, Any]:
self._migrate_legacy_document_parsing_file()
payload = self._normalize_document_parsing(
{**DEFAULT_DOCUMENT_PARSING_SETTINGS, **settings}
)
_atomic_write_json(self.path_for(DOCUMENT_PARSING_SETTINGS_NAME), payload)
return payload
def load_mineru(self, *, include_process_overrides: bool = True) -> dict[str, Any]:
"""Return the MinerU engine slice (flat) for legacy readers.
Backed by the v2 structure on disk; env overrides apply to the slice.
"""
slice_ = dict(
self.load_document_parsing(include_process_overrides=False)["engines"][
DOCUMENT_PARSING_ENGINE_MINERU
]
)
if include_process_overrides:
slice_ = self._apply_mineru_process_overrides(slice_)
return slice_
def save_mineru(self, settings: dict[str, Any]) -> dict[str, Any]:
"""Persist only the MinerU engine slice, preserving the other engines."""
full = self.load_document_parsing(include_process_overrides=False)
engines = dict(full["engines"])
engines[DOCUMENT_PARSING_ENGINE_MINERU] = self._normalize_mineru_engine(
{**_DEFAULT_MINERU_ENGINE, **settings}
)
payload = self._normalize_document_parsing({**full, "engines": engines})
_atomic_write_json(self.path_for(DOCUMENT_PARSING_SETTINGS_NAME), payload)
return payload["engines"][DOCUMENT_PARSING_ENGINE_MINERU]
def load_pageindex(self, *, include_process_overrides: bool = True) -> dict[str, Any]:
payload = self._load_or_create(
"pageindex",
DEFAULT_PAGEINDEX_SETTINGS,
self._normalize_pageindex,
)
if include_process_overrides:
payload = self._apply_pageindex_process_overrides(payload)
return payload
def save_pageindex(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = self._normalize_pageindex({**DEFAULT_PAGEINDEX_SETTINGS, **settings})
_atomic_write_json(self.path_for("pageindex"), payload)
return payload
def load_query_rewrite(self, *, include_process_overrides: bool = True) -> dict[str, Any]:
payload = self._load_or_create(
"query_rewrite",
DEFAULT_QUERY_REWRITE_SETTINGS,
self._normalize_query_rewrite,
)
if include_process_overrides:
payload = self._apply_query_rewrite_process_overrides(payload)
return payload
def save_query_rewrite(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = self._normalize_query_rewrite({**DEFAULT_QUERY_REWRITE_SETTINGS, **settings})
_atomic_write_json(self.path_for("query_rewrite"), payload)
return payload
def load_ima(self, *, include_process_overrides: bool = True) -> dict[str, Any]:
payload = self._load_or_create("ima", DEFAULT_IMA_SETTINGS, self._normalize_ima)
if include_process_overrides:
payload = self._apply_ima_process_overrides(payload)
return payload
def save_ima(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = self._normalize_ima({**DEFAULT_IMA_SETTINGS, **settings})
_atomic_write_json(self.path_for("ima"), payload)
return payload
def load_llamaindex(self, *, include_process_overrides: bool = True) -> dict[str, Any]:
payload = self._load_or_create(
"llamaindex",
DEFAULT_LLAMAINDEX_SETTINGS,
self._normalize_llamaindex,
)
if include_process_overrides:
payload = self._apply_llamaindex_process_overrides(payload)
return payload
def save_llamaindex(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = self._normalize_llamaindex({**DEFAULT_LLAMAINDEX_SETTINGS, **settings})
_atomic_write_json(self.path_for("llamaindex"), payload)
return payload
def load_graphrag(self) -> dict[str, Any]:
return self._load_or_create("graphrag", DEFAULT_GRAPHRAG_SETTINGS, self._normalize_graphrag)
def save_graphrag(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = self._normalize_graphrag({**DEFAULT_GRAPHRAG_SETTINGS, **settings})
_atomic_write_json(self.path_for("graphrag"), payload)
return payload
def load_lightrag(self) -> dict[str, Any]:
path = self.path_for("lightrag")
if path.exists():
# Invalid role settings must never become legacy chat-model fallback.
with path.open(encoding="utf-8") as handle:
loaded = json.load(handle)
if not isinstance(loaded, dict):
raise ValueError("LightRAG settings must be an object.")
# Existing files without a version predate independent roles.
normalized = self._normalize_lightrag(
{**DEFAULT_LIGHTRAG_SETTINGS, "version": 1, **loaded}
)
if normalized != loaded:
_atomic_write_json(path, normalized)
return normalized
return self._load_or_create("lightrag", DEFAULT_LIGHTRAG_SETTINGS, self._normalize_lightrag)
def save_lightrag(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = self._normalize_lightrag({**DEFAULT_LIGHTRAG_SETTINGS, **settings})
_atomic_write_json(self.path_for("lightrag"), payload)
return payload
def load_lightrag_server(self) -> dict[str, Any]:
return self._load_or_create(
"lightrag_server",
DEFAULT_LIGHTRAG_SERVER_SETTINGS,
self._normalize_lightrag_server,
)
def save_lightrag_server(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = self._normalize_lightrag_server({**DEFAULT_LIGHTRAG_SERVER_SETTINGS, **settings})
_atomic_write_json(self.path_for("lightrag_server"), payload)
return payload
def ensure_defaults(self) -> None:
self.load_system(include_process_overrides=False)
self.load_auth(include_process_overrides=False)
self.load_integrations(include_process_overrides=False)
self.load_mineru(include_process_overrides=False)
self.load_pageindex(include_process_overrides=False)
self.load_ima(include_process_overrides=False)
self.load_llamaindex(include_process_overrides=False)
self.load_query_rewrite(include_process_overrides=False)
self.load_graphrag()
self.load_lightrag()
self.load_lightrag_server()
def render_environment(self) -> dict[str, str]:
"""Render non-model settings into process env names for subprocesses."""
system = self.load_system()
auth = self.load_auth()
integrations = self.load_integrations()
return {
"DEEPTUTOR_VERSION_CHECK_ENABLED": _bool_env(system["version_check_enabled"]),
"BACKEND_PORT": str(system["backend_port"]),
"BACKEND_WORKERS": str(system["backend_workers"]),
"FRONTEND_PORT": str(system["frontend_port"]),
"NEXT_PUBLIC_API_BASE_EXTERNAL": system["next_public_api_base_external"],
"NEXT_PUBLIC_API_BASE": system["next_public_api_base"],
"CORS_ORIGIN": system["cors_origin"],
"CORS_ORIGINS": ",".join(system["cors_origins"]),
"DISABLE_SSL_VERIFY": _bool_env(system["disable_ssl_verify"]),
"CHAT_ATTACHMENT_DIR": system["chat_attachment_dir"],
"DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS": _bool_env(system["sandbox_allow_subprocess"]),
"AUTH_ENABLED": _bool_env(auth["enabled"]),
"AUTH_USERNAME": auth["username"],
"AUTH_PASSWORD_HASH": auth["password_hash"],
"AUTH_TOKEN_EXPIRE_HOURS": str(auth["token_expire_hours"]),
"AUTH_COOKIE_SECURE": _bool_env(auth["cookie_secure"]),
"AUTH_PRIVATE_LOGIN_HOSTS": ",".join(auth["private_login_hosts"]),
"NEXT_PUBLIC_AUTH_ENABLED": _bool_env(auth["enabled"]),
# Consumed server-side by the Next.js middleware (web/proxy.ts) at
# request time — NOT inlined into the browser bundle. The proxy
# rewrites /api/* and /ws/* to DEEPTUTOR_API_BASE_URL and uses
# DEEPTUTOR_AUTH_ENABLED to gate the login redirect. The launcher and
# the Docker entrypoint both export these through render_environment,
# so the two deployment paths stay in sync. DEEPTUTOR_API_BASE_URL is
# the address the frontend *server* uses to reach the backend; the
# browser itself only ever talks to the frontend origin.
#
# The fallback is the IPv4 loopback, not "localhost": on a dual-stack
# host that name resolves to ::1 first, while uvicorn binds 0.0.0.0
# (IPv4 only), so every rewritten /api/* request fails to connect.
# The launcher passes the same literal (see runtime/launcher.py), so
# both deployment paths agree.
"DEEPTUTOR_API_BASE_URL": (
system["next_public_api_base"]
or system["next_public_api_base_external"]
or f"http://127.0.0.1:{system['backend_port']}"
),
"DEEPTUTOR_AUTH_ENABLED": _bool_env(auth["enabled"]),
"POCKETBASE_URL": integrations["pocketbase_url"],
"POCKETBASE_PORT": str(integrations["pocketbase_port"]),
"POCKETBASE_EXTERNAL_URL": integrations["pocketbase_external_url"],
"POCKETBASE_ADMIN_EMAIL": integrations["pocketbase_admin_email"],
"POCKETBASE_ADMIN_PASSWORD": integrations["pocketbase_admin_password"],
}
def export_environment(self, *, overwrite: bool = True) -> dict[str, str]:
env = self.render_environment()
for key, value in env.items():
# Read through the same view the override policy reads, so "the
# operator set this" means one thing in both places.
current = self.process_env.get(key)
if (
current
and key not in self._settings_derived_keys
and self._internal_exported_values.get(key) != current
):
self._external_process_keys.add(key)
if overwrite or key not in os.environ:
os.environ[key] = value
if key not in self._external_process_keys:
self._internal_exported_values[key] = value
return env
def settings_derived_keys(self) -> frozenset[str]:
"""Variables this process exported out of the settings files.
What a child needs in order to read its inherited environment correctly
(see :data:`SETTINGS_DERIVED_ENV_KEYS`). Anything the operator had
already set is excluded: there the environment is the authority and the
child must keep honouring it, exactly as this process does.
"""
return frozenset(self._internal_exported_values)
def _process_env_value(self, key: str) -> str:
if self._ignore_process_overrides():
return ""
if key in self._settings_derived_keys:
# A parent DeepTutor process rendered this out of the settings files,
# so the files stay in charge and a later save takes effect live
# (#1536). An operator-set variable is never on that list.
return ""
value = self.process_env.get(key, "")
if not value:
return ""
if key in self._external_process_keys:
return value
internal_value = self._internal_exported_values.get(key)
if internal_value is not None and value == internal_value:
return ""
return value
def _load_or_create(
self,
name: str,
defaults: dict[str, Any],
normalizer: Callable[[dict[str, Any]], dict[str, Any]],
) -> dict[str, Any]:
path = self.path_for(name)
loaded = _json_object(path)
if loaded:
normalized = normalizer({**defaults, **loaded})
if normalized != loaded:
_atomic_write_json(path, normalized)
return normalized
normalized = normalizer(_deepcopy_default(defaults))
_atomic_write_json(path, normalized)
return normalized
def _migrate_legacy_document_parsing_file(self) -> None:
"""Rename the legacy ``mineru.json`` to ``document_parsing.json``.
The file holds the full multi-engine parsing config; the MinerU-specific
name predates the other engines. Move it in place on first access so
existing installs keep their settings (content migration to v2 happens in
``_normalize_document_parsing``). Idempotent: a no-op once migrated.
"""
new_path = self.path_for(DOCUMENT_PARSING_SETTINGS_NAME)
legacy_path = self.path_for(_LEGACY_DOCUMENT_PARSING_SETTINGS_NAME)
if not legacy_path.exists():
return
if new_path.exists():
# New file is authoritative; drop the stale legacy copy.
legacy_path.unlink(missing_ok=True)
return
legacy_path.rename(new_path)
def _ignore_process_overrides(self) -> bool:
return _coerce_bool(self.process_env.get(IGNORE_PROCESS_OVERRIDES_ENV), False)
def _apply_system_process_overrides(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = dict(settings)
if value := self._process_env_value("DEEPTUTOR_VERSION_CHECK_ENABLED"):
payload["version_check_enabled"] = value
if value := self._process_env_value("BACKEND_PORT"):
payload["backend_port"] = value
if value := self._process_env_value("FRONTEND_PORT"):
payload["frontend_port"] = value
if value := self._process_env_value("NEXT_PUBLIC_API_BASE_EXTERNAL"):
payload["next_public_api_base_external"] = value
if value := self._process_env_value("PUBLIC_API_BASE"):
payload["next_public_api_base_external"] = value
if value := self._process_env_value("NEXT_PUBLIC_API_BASE"):
payload["next_public_api_base"] = value
if value := self._process_env_value("CORS_ORIGIN"):
payload["cors_origin"] = value
if value := self._process_env_value("CORS_ORIGINS"):
payload["cors_origins"] = value
if value := self._process_env_value("DISABLE_SSL_VERIFY"):
payload["disable_ssl_verify"] = value
if value := self._process_env_value("CHAT_ATTACHMENT_DIR"):
payload["chat_attachment_dir"] = value
if value := (
self._process_env_value("DEEPTUTOR_BACKEND_WORKERS")
or self._process_env_value("BACKEND_WORKERS")
):
payload["backend_workers"] = value
if value := self._process_env_value("DEEPTUTOR_SANDBOX_ALLOW_SUBPROCESS"):
payload["sandbox_allow_subprocess"] = value
if value := self._process_env_value("DEEPTUTOR_CAPABILITY_ROUTING_ENABLED"):
payload["capability_routing_enabled"] = value
if value := self._process_env_value("CHAT_ATTACHMENT_MAX_FILE_MB"):
payload["chat_attachment_max_file_mb"] = value
if value := self._process_env_value("CHAT_ATTACHMENT_MAX_TOTAL_MB"):
payload["chat_attachment_max_total_mb"] = value
if value := self._process_env_value("CHAT_ATTACHMENT_MAX_CHARS_PER_DOC"):
payload["chat_attachment_max_chars_per_doc"] = value
if value := self._process_env_value("CHAT_ATTACHMENT_MAX_CHARS_TOTAL"):
payload["chat_attachment_max_chars_total"] = value
if value := self._process_env_value("CHAT_PRIOR_IMAGE_REINJECT_MAX"):
payload["chat_prior_image_reinject_max"] = value
guard = dict(payload.get("security_guard") or {})
for env_name, key in _SECURITY_GUARD_ENV_KEYS:
if value := self._process_env_value(env_name):
guard[key] = value
payload["security_guard"] = guard
return self._normalize_system(payload)
def _apply_auth_process_overrides(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = dict(settings)
if value := (
self._process_env_value("AUTH_ENABLED")
or self._process_env_value("NEXT_PUBLIC_AUTH_ENABLED")
):
payload["enabled"] = value
if value := self._process_env_value("AUTH_USERNAME"):
payload["username"] = value
if value := self._process_env_value("AUTH_PASSWORD_HASH"):
payload["password_hash"] = value
if value := self._process_env_value("AUTH_TOKEN_EXPIRE_HOURS"):
payload["token_expire_hours"] = value
if value := self._process_env_value("AUTH_COOKIE_SECURE"):
payload["cookie_secure"] = value
if value := self._process_env_value("AUTH_PRIVATE_LOGIN_HOSTS"):
payload["private_login_hosts"] = value
return self._normalize_auth(payload)
def _apply_integrations_process_overrides(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = dict(settings)
if value := self._process_env_value("POCKETBASE_URL"):
payload["pocketbase_url"] = value
if value := self._process_env_value("POCKETBASE_PORT"):
payload["pocketbase_port"] = value
if value := self._process_env_value("POCKETBASE_EXTERNAL_URL"):
payload["pocketbase_external_url"] = value
if value := self._process_env_value("POCKETBASE_ADMIN_EMAIL"):
payload["pocketbase_admin_email"] = value
if value := self._process_env_value("POCKETBASE_ADMIN_PASSWORD"):
payload["pocketbase_admin_password"] = value
coordination = dict(payload.get("turn_coordination") or {})
if value := self._process_env_value("DEEPTUTOR_TURN_COORDINATION_BACKEND"):
coordination["backend"] = value
if value := self._process_env_value("DEEPTUTOR_REDIS_URL"):
coordination["redis_url"] = value
if value := self._process_env_value("DEEPTUTOR_REDIS_KEY_PREFIX"):
coordination["key_prefix"] = value
payload["turn_coordination"] = coordination
return self._normalize_integrations(payload)
def _apply_mineru_process_overrides(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = dict(settings)
if value := self._process_env_value("MINERU_MODE"):
payload["mode"] = value
if value := self._process_env_value("MINERU_API_BASE_URL"):
payload["api_base_url"] = value
if value := self._process_env_value("MINERU_API_TOKEN"):
payload["api_token"] = value
if value := self._process_env_value("MINERU_LOCAL_CLI_PATH"):
payload["local_cli_path"] = value
if value := self._process_env_value("MINERU_MODEL_SOURCE"):
payload["model_download_source"] = value
if value := self._process_env_value("MINERU_MODEL_DOWNLOAD_ENDPOINT"):
payload["model_download_endpoint"] = value
if value := self._process_env_value("MINERU_MODEL_VERSION"):
payload["model_version"] = value
if value := self._process_env_value("MINERU_LANGUAGE"):
payload["language"] = value
if value := self._process_env_value("MINERU_ALLOW_LOCAL_MODEL_DOWNLOAD"):
payload["allow_local_model_download"] = _coerce_bool(value, False)
return self._normalize_mineru_engine(payload)
def _apply_pageindex_process_overrides(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = dict(settings)
if value := self._process_env_value("PAGEINDEX_API_KEY"):
payload["api_key"] = value
return self._normalize_pageindex(payload)
def _normalize_pageindex(self, settings: dict[str, Any]) -> dict[str, Any]:
return {
"version": 1,
"api_key": _string(settings.get("api_key")),
}
def _apply_query_rewrite_process_overrides(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = dict(settings)
if value := self._process_env_value("DEEPTUTOR_QUERY_REWRITE_ENABLED"):
payload["enabled"] = value
if value := self._process_env_value("DEEPTUTOR_QUERY_REWRITE_STRATEGY"):
payload["strategy"] = value
if value := self._process_env_value("DEEPTUTOR_QUERY_REWRITE_MODEL"):
payload["model"] = value
if value := self._process_env_value("DEEPTUTOR_QUERY_REWRITE_TIMEOUT_SECONDS"):
payload["timeout_seconds"] = value
if value := self._process_env_value("DEEPTUTOR_QUERY_REWRITE_MIN_QUERY_CHARS"):
payload["min_query_chars"] = value
return self._normalize_query_rewrite(payload)
def _normalize_query_rewrite(self, settings: dict[str, Any]) -> dict[str, Any]:
strategy = str(settings.get("strategy") or "standalone").strip().lower()
if strategy not in QUERY_REWRITE_STRATEGIES:
strategy = "standalone"
try:
timeout = float(settings.get("timeout_seconds", 5.0))
except (TypeError, ValueError):
timeout = 5.0
timeout = min(max(timeout, 0.5), 60.0)
try:
min_chars = int(settings.get("min_query_chars", 12))
except (TypeError, ValueError):
min_chars = 12
min_chars = min(max(min_chars, 0), 500)
return {
"version": 1,
"enabled": _coerce_bool(settings.get("enabled"), False),
"strategy": strategy,
"model": str(settings.get("model") or "").strip(),
"timeout_seconds": timeout,
"min_query_chars": min_chars,
}
def _apply_ima_process_overrides(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = dict(settings)
if value := self._process_env_value("IMA_CLIENT_ID"):
payload["client_id"] = value
if value := self._process_env_value("IMA_API_KEY"):
payload["api_key"] = value
return self._normalize_ima(payload)
def _normalize_ima(self, settings: dict[str, Any]) -> dict[str, Any]:
return {
"version": 1,
"client_id": _string(settings.get("client_id")),
"api_key": _string(settings.get("api_key")),
}
def _apply_llamaindex_process_overrides(self, settings: dict[str, Any]) -> dict[str, Any]:
# Only the retrieval profile had an env override historically
# (DEEPTUTOR_RAG_RETRIEVAL_PROFILE / RAG_RETRIEVAL_PROFILE); preserve it.
payload = dict(settings)
if value := (
self._process_env_value("DEEPTUTOR_RAG_RETRIEVAL_PROFILE")
or self._process_env_value("RAG_RETRIEVAL_PROFILE")
):
payload["retrieval_profile"] = value
return self._normalize_llamaindex(payload)
def _normalize_llamaindex(self, settings: dict[str, Any]) -> dict[str, Any]:
profile = _string(settings.get("retrieval_profile")).lower()
if profile not in _LLAMAINDEX_PROFILES:
profile = LLAMAINDEX_HYBRID_PROFILE
vector_index_type = _string(settings.get("vector_index_type")).lower()
if vector_index_type not in _LLAMAINDEX_VECTOR_INDEX_TYPES:
vector_index_type = LLAMAINDEX_FLAT_VECTOR_INDEX
chunk_size = _coerce_clamped_int(settings.get("chunk_size"), 512, 64, 8192)
# Overlap must stay below the chunk size or chunking degenerates.
chunk_overlap = _coerce_clamped_int(
settings.get("chunk_overlap"), 50, 0, max(0, chunk_size - 1)
)
return {
"version": 1,
"retrieval_profile": profile,
"top_k": _coerce_clamped_int(settings.get("top_k"), 5, 1, 50),
"vector_top_k_multiplier": _coerce_clamped_int(
settings.get("vector_top_k_multiplier"), 2, 1, 10
),
"bm25_top_k_multiplier": _coerce_clamped_int(
settings.get("bm25_top_k_multiplier"), 2, 1, 10
),
"reranker_model": _string(settings.get("reranker_model"))[:200],
"rerank_top_k": _coerce_clamped_int(settings.get("rerank_top_k"), 50, 1, 100),
"vector_index_type": vector_index_type,
"hnsw_m": _coerce_clamped_int(settings.get("hnsw_m"), 32, 4, 64),
"hnsw_ef_construction": _coerce_clamped_int(
settings.get("hnsw_ef_construction"), 200, 16, 512
),
"hnsw_ef_search": _coerce_clamped_int(settings.get("hnsw_ef_search"), 64, 1, 512),
"chunk_size": chunk_size,
"chunk_overlap": chunk_overlap,
"image_description_concurrency": _coerce_clamped_int(
settings.get("image_description_concurrency"), 4, 1, 16
),
"image_description_batch_size": _coerce_clamped_int(
settings.get("image_description_batch_size"), 1, 1, 8
),
"image_description_timeout_seconds": _coerce_clamped_int(
settings.get("image_description_timeout_seconds"), 60, 5, 600
),
}
def _normalize_response_type(self, value: Any) -> str:
# GraphRAG/LightRAG accept any answer-style string; just trim + cap so a
# pathological value can't blow up a prompt.
text = _string(value) or "Multiple Paragraphs"
return text[:80]
def _normalize_graphrag(self, settings: dict[str, Any]) -> dict[str, Any]:
return {
"version": 1,
"response_type": self._normalize_response_type(settings.get("response_type")),
"community_level": _coerce_clamped_int(settings.get("community_level"), 2, 0, 5),
"dynamic_community_selection": _coerce_bool(
settings.get("dynamic_community_selection"), False
),
}
def _normalize_lightrag(self, settings: dict[str, Any]) -> dict[str, Any]:
from .lightrag_roles import LightRagRoleModels
version = settings.get("version", 1)
if type(version) is not int or version not in {1, 2}:
raise ValueError("Unsupported LightRAG settings version.")
# Missing means a released, legacy setting. Never turn malformed new
# configuration back into a legacy model fallback.
role_models = settings.get("role_models")
roles = (
LightRagRoleModels.model_validate(role_models).model_dump()
if "role_models" in settings
else None
)
result = {
"version": 2 if roles is not None or settings.get("version") == 2 else 1,
"top_k": _coerce_clamped_int(settings.get("top_k"), 60, 1, 200),
"response_type": self._normalize_response_type(settings.get("response_type")),
"max_concurrent_files": _coerce_clamped_int(
settings.get("max_concurrent_files"), 1, 1, 16
),
"llm_model_max_async": _coerce_clamped_int(
settings.get("llm_model_max_async"), 4, 1, 32
),
"entity_extract_max_gleaning": _coerce_clamped_int(
settings.get("entity_extract_max_gleaning"), 1, 0, 5
),
"llm_timeout": _coerce_clamped_int(settings.get("llm_timeout"), 240, 60, 3600),
"llm_profile_id": _string(settings.get("llm_profile_id"))[:128],
"llm_model_id": _string(settings.get("llm_model_id"))[:128],
}
if roles is not None:
result["role_models"] = roles
return result
def _normalize_lightrag_server(self, settings: dict[str, Any]) -> dict[str, Any]:
return {
"version": 1,
"server_url": _string(settings.get("server_url")).rstrip("/"),
"api_key": _string(settings.get("api_key")),
}
def _normalize_document_parsing(self, settings: dict[str, Any]) -> dict[str, Any]:
"""Normalize the full v2 structure, migrating a v1 flat file in place.
v1 is detected by legacy flat MinerU keys at the top level (v2 never
writes them there). When migrating, those values seed ``engines.mineru``
and the active engine is pinned to MinerU so the install's behavior is
preserved. Each known engine is always present (defaults fill gaps).
"""
settings = dict(settings)
legacy_flat = {key: settings[key] for key in _MINERU_ENGINE_KEYS if key in settings}
migrating = bool(legacy_flat)
raw_engines = settings.get("engines")
engines_in = dict(raw_engines) if isinstance(raw_engines, dict) else {}
if legacy_flat:
mineru_in = dict(engines_in.get(DOCUMENT_PARSING_ENGINE_MINERU) or {})
engines_in[DOCUMENT_PARSING_ENGINE_MINERU] = {**mineru_in, **legacy_flat}
engines_out = {
DOCUMENT_PARSING_ENGINE_TEXT_ONLY: self._normalize_text_only_engine(
engines_in.get(DOCUMENT_PARSING_ENGINE_TEXT_ONLY) or {}
),
DOCUMENT_PARSING_ENGINE_MINERU: self._normalize_mineru_engine(
engines_in.get(DOCUMENT_PARSING_ENGINE_MINERU) or {}
),
DOCUMENT_PARSING_ENGINE_DOCLING: self._normalize_docling_engine(
engines_in.get(DOCUMENT_PARSING_ENGINE_DOCLING) or {}
),
DOCUMENT_PARSING_ENGINE_MARKITDOWN: self._normalize_markitdown_engine(
engines_in.get(DOCUMENT_PARSING_ENGINE_MARKITDOWN) or {}
),
DOCUMENT_PARSING_ENGINE_PYMUPDF4LLM: self._normalize_pymupdf4llm_engine(
engines_in.get(DOCUMENT_PARSING_ENGINE_PYMUPDF4LLM) or {}
),
DOCUMENT_PARSING_ENGINE_LITEPARSE: self._normalize_liteparse_engine(
engines_in.get(DOCUMENT_PARSING_ENGINE_LITEPARSE) or {}
),
DOCUMENT_PARSING_ENGINE_TIKA: self._normalize_tika_engine(
engines_in.get(DOCUMENT_PARSING_ENGINE_TIKA) or {}
),
}
engine = _string(settings.get("engine")).lower().replace("-", "_").replace(" ", "_")
if migrating:
engine = DOCUMENT_PARSING_ENGINE_MINERU
if engine not in _DOCUMENT_PARSING_ENGINES:
engine = _DEFAULT_DOCUMENT_PARSING_ENGINE
return {
"version": 2,
"engine": engine,
"image_caption": _coerce_bool(settings.get("image_caption"), False),
"image_description_model": normalize_image_description_model(
settings.get("image_description_model")
),
"engines": engines_out,
}
def _normalize_mineru_engine(self, settings: dict[str, Any]) -> dict[str, Any]:
mode = _string(settings.get("mode")).lower()
if mode not in _MINERU_MODES:
mode = MINERU_MODE_LOCAL
model_version = _string(settings.get("model_version")).lower()
if model_version not in _MINERU_MODEL_VERSIONS:
model_version = "pipeline"
download_source = _string(settings.get("model_download_source")).lower()
if download_source not in _MINERU_DOWNLOAD_SOURCES:
download_source = "huggingface"
language = _string(settings.get("language")) or "auto"
return {
"mode": mode,
"api_base_url": _string(settings.get("api_base_url")).rstrip("/")
or "https://mineru.net",
"api_token": _string_or_list(settings.get("api_token")),
"local_cli_path": _string(settings.get("local_cli_path")),
"model_download_source": download_source,
"model_download_endpoint": _string(settings.get("model_download_endpoint")).rstrip("/"),
"model_version": model_version,
"language": language,
"enable_formula": _coerce_bool(settings.get("enable_formula"), True),
"enable_table": _coerce_bool(settings.get("enable_table"), True),
"is_ocr": _coerce_bool(settings.get("is_ocr"), False),
"max_pages_per_part": _coerce_clamped_int(
settings.get("max_pages_per_part"), 180, 1, 200
),
"normalize_tiny_scans": _coerce_bool(settings.get("normalize_tiny_scans"), False),
"allow_local_model_download": _coerce_bool(
settings.get("allow_local_model_download"), False
),
}
def _normalize_docling_engine(self, settings: dict[str, Any]) -> dict[str, Any]:
mode = _string(settings.get("mode")).lower()
if mode not in _DOCLING_MODES:
mode = DOCLING_MODE_LOCAL
return {
"mode": mode,
"api_base_url": _string(settings.get("api_base_url")).rstrip("/")
or "http://localhost:5001",
"api_token": _string(settings.get("api_token")),
"do_ocr": _coerce_bool(settings.get("do_ocr"), False),
"do_table_structure": _coerce_bool(settings.get("do_table_structure"), True),
"allow_local_model_download": _coerce_bool(
settings.get("allow_local_model_download"), False
),
}
def _apply_docling_process_overrides(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = dict(settings)
if value := self._process_env_value("DOCLING_MODE"):
payload["mode"] = value
if value := self._process_env_value("DOCLING_API_BASE_URL"):
payload["api_base_url"] = value
if value := self._process_env_value("DOCLING_API_TOKEN"):
payload["api_token"] = value
return self._normalize_docling_engine(payload)
def _normalize_tika_engine(self, settings: dict[str, Any]) -> dict[str, Any]:
return {
"server_url": _string(settings.get("server_url")).rstrip("/")
or "http://localhost:9998",
}
def _apply_tika_process_overrides(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = dict(settings)
if value := self._process_env_value("TIKA_SERVER_URL"):
payload["server_url"] = value
return self._normalize_tika_engine(payload)
def _normalize_markitdown_engine(self, settings: dict[str, Any]) -> dict[str, Any]:
return {
"enable_llm_image_description": _coerce_bool(
settings.get("enable_llm_image_description"), False
),
}
def _normalize_liteparse_engine(self, settings: dict[str, Any]) -> dict[str, Any]:
image_mode = _string(settings.get("image_mode")).lower() or "placeholder"
if image_mode not in LITEPARSE_IMAGE_MODES:
image_mode = "placeholder"
return {
"image_mode": image_mode,
"extract_links": _coerce_bool(settings.get("extract_links"), True),
"extract_images": _coerce_bool(settings.get("extract_images"), False),
"max_pages": _coerce_clamped_int(settings.get("max_pages"), 0, 0, 100_000),
}
def _normalize_pymupdf4llm_engine(self, settings: dict[str, Any]) -> dict[str, Any]:
image_format = _string(settings.get("image_format")).lower() or "png"
if image_format not in _PYMUPDF4LLM_IMAGE_FORMATS:
image_format = "png"
return {
"write_images": _coerce_bool(settings.get("write_images"), True),
"image_format": image_format,
"image_dpi": _coerce_clamped_int(settings.get("image_dpi"), 150, 72, 600),
}
def _normalize_text_only_engine(self, _settings: dict[str, Any]) -> dict[str, Any]:
return {}
def _normalize_system(self, settings: dict[str, Any]) -> dict[str, Any]:
public_api_base = _string(settings.get("next_public_api_base_external")) or _string(
settings.get("public_api_base")
)
raw_source_filter = settings.get("web_search_source_filtering")
source_filter = raw_source_filter if isinstance(raw_source_filter, dict) else {}
max_file_mb = _coerce_clamped_int(
settings.get("chat_attachment_max_file_mb"),
DEFAULT_SYSTEM_SETTINGS["chat_attachment_max_file_mb"],
*CHAT_ATTACHMENT_MAX_FILE_MB_RANGE,
)
max_total_mb = _coerce_clamped_int(
settings.get("chat_attachment_max_total_mb"),
DEFAULT_SYSTEM_SETTINGS["chat_attachment_max_total_mb"],
*CHAT_ATTACHMENT_MAX_TOTAL_MB_RANGE,
)
# A per-message total below the per-file cap is contradictory; lift it.
max_total_mb = max(max_total_mb, max_file_mb)
raw_guard = settings.get("security_guard")
guard = raw_guard if isinstance(raw_guard, dict) else {}
guard_defaults = DEFAULT_SYSTEM_SETTINGS["security_guard"]
return {
"version": 1,
"version_check_enabled": _coerce_bool(settings.get("version_check_enabled"), True),
"backend_port": _coerce_port(settings.get("backend_port"), 8001),
"backend_workers": _coerce_clamped_int(settings.get("backend_workers"), 1, 1, 64),
"frontend_port": _coerce_port(settings.get("frontend_port"), 3782),
"next_public_api_base_external": public_api_base,
"next_public_api_base": _string(settings.get("next_public_api_base")),
"cors_origin": _string(settings.get("cors_origin")),
"cors_origins": _coerce_origins(settings.get("cors_origins")),
"disable_ssl_verify": _coerce_bool(settings.get("disable_ssl_verify"), False),
"chat_attachment_dir": _string(settings.get("chat_attachment_dir")),
"sandbox_allow_subprocess": _coerce_bool(
settings.get("sandbox_allow_subprocess"), True
),
"capability_routing_enabled": _coerce_bool(
settings.get("capability_routing_enabled"), False
),
"web_search_source_filtering": {
"enabled": _coerce_bool(source_filter.get("enabled"), True),
"blocked_domains": _string_or_list(source_filter.get("blocked_domains")),
"trusted_domains": _string_or_list(source_filter.get("trusted_domains")),
"content_filtering": _coerce_bool(source_filter.get("content_filtering"), True),
"use_educational_trusted_domains": _coerce_bool(
source_filter.get("use_educational_trusted_domains"), False
),
"use_moderation": _coerce_bool(source_filter.get("use_moderation"), False),
},
"chat_attachment_max_file_mb": max_file_mb,
"chat_attachment_max_total_mb": max_total_mb,
"chat_prior_image_reinject_max": _coerce_clamped_int(
settings.get("chat_prior_image_reinject_max"),
DEFAULT_SYSTEM_SETTINGS["chat_prior_image_reinject_max"],
*CHAT_PRIOR_IMAGE_REINJECT_RANGE,
),
"chat_attachment_max_chars_per_doc": _coerce_clamped_int(
settings.get("chat_attachment_max_chars_per_doc"),
DEFAULT_SYSTEM_SETTINGS["chat_attachment_max_chars_per_doc"],
*CHAT_ATTACHMENT_CHARS_RANGE,
),
"chat_attachment_max_chars_total": _coerce_clamped_int(
settings.get("chat_attachment_max_chars_total"),
DEFAULT_SYSTEM_SETTINGS["chat_attachment_max_chars_total"],
*CHAT_ATTACHMENT_CHARS_RANGE,
),
"security_guard": {
"enabled": _coerce_bool(guard.get("enabled"), False),
"rate_limit": _coerce_clamped_int(
guard.get("rate_limit"), guard_defaults["rate_limit"], 1, 1_000_000
),
"rate_limit_window": _coerce_clamped_int(
guard.get("rate_limit_window"), guard_defaults["rate_limit_window"], 1, 86_400
),
# An absent key keeps the loopback default; an explicit empty
# list means "trust no proxy".
"trusted_proxies": _host_list(guard["trusted_proxies"])
if "trusted_proxies" in guard
else list(guard_defaults["trusted_proxies"]),
"exempt_ips": _host_list(guard["exempt_ips"])
if "exempt_ips" in guard
else list(guard_defaults["exempt_ips"]),
"whitelist": _host_list(guard.get("whitelist")),
"blacklist": _host_list(guard.get("blacklist")),
},
}
def _normalize_auth(self, settings: dict[str, Any]) -> dict[str, Any]:
return {
"version": 1,
"enabled": _coerce_bool(settings.get("enabled"), False),
"username": _string(settings.get("username")) or "admin",
"password_hash": _string(settings.get("password_hash")),
"token_expire_hours": max(1, _coerce_int(settings.get("token_expire_hours"), 24)),
"cookie_secure": _coerce_bool(settings.get("cookie_secure"), False),
"private_login_hosts": _host_list(settings.get("private_login_hosts")),
}
def _normalize_integrations(self, settings: dict[str, Any]) -> dict[str, Any]:
raw_coordination = settings.get("turn_coordination")
coordination = raw_coordination if isinstance(raw_coordination, dict) else {}
backend = _string(coordination.get("backend")).lower()
if backend not in {"memory", "redis"}:
backend = "memory"
key_prefix = _string(coordination.get("key_prefix")).strip(":") or "deeptutor"
return {
"version": 2,
"pocketbase_url": _string(settings.get("pocketbase_url")).rstrip("/"),
"pocketbase_port": _coerce_port(settings.get("pocketbase_port"), 8090),
"pocketbase_external_url": _string(settings.get("pocketbase_external_url")).rstrip("/"),
"pocketbase_admin_email": _string(settings.get("pocketbase_admin_email")),
"pocketbase_admin_password": _string(settings.get("pocketbase_admin_password")),
"turn_coordination": {
"backend": backend,
"redis_url": _string(coordination.get("redis_url")),
"key_prefix": key_prefix,
"lease_ttl_seconds": _coerce_clamped_int(
coordination.get("lease_ttl_seconds"), 30, 10, 300
),
"renew_interval_seconds": _coerce_clamped_int(
coordination.get("renew_interval_seconds"), 10, 1, 100
),
"recovery_interval_seconds": _coerce_clamped_int(
coordination.get("recovery_interval_seconds"), 10, 1, 300
),
"stream_retention_seconds": _coerce_clamped_int(
coordination.get("stream_retention_seconds"), 86_400, 60, 2_592_000
),
},
}
def _bool_env(value: Any) -> str:
return "true" if _coerce_bool(value, False) else "false"
def _global_settings_dir() -> Path:
try:
from deeptutor.multi_user.paths import get_admin_path_service
return get_admin_path_service().get_settings_dir()
except Exception:
return get_path_service().get_settings_dir()
def get_runtime_settings_service() -> RuntimeSettingsService:
return RuntimeSettingsService.get_instance(_global_settings_dir())
def ensure_runtime_settings_files() -> None:
"""Create missing JSON settings files using migration/default rules.
Startup callers use this as the single "settings bootstrap" hook:
missing runtime files are created with safe defaults. Process
environment variables remain deployment overrides and are intentionally
not persisted into the JSON files.
"""
get_runtime_settings_service().ensure_defaults()
from .model_catalog import get_model_catalog_service
get_model_catalog_service().load()
def load_system_settings() -> dict[str, Any]:
return get_runtime_settings_service().load_system()
@dataclass(frozen=True)
class ChatAttachmentLimits:
"""Effective chat-attachment policy, in enforcement-ready units."""
max_file_bytes: int
max_total_bytes: int
max_chars_per_doc: int
max_chars_total: int
def get_chat_attachment_limits() -> ChatAttachmentLimits:
"""Resolve the chat attachment policy from system.json (+ env overrides).
Read at call time by every enforcement site (turn runtime extraction,
partner uploads, the composer via the settings API) so edits apply to the
next message without a restart.
"""
system = load_system_settings()
return ChatAttachmentLimits(
max_file_bytes=int(system["chat_attachment_max_file_mb"]) * 1024 * 1024,
max_total_bytes=int(system["chat_attachment_max_total_mb"]) * 1024 * 1024,
max_chars_per_doc=int(system["chat_attachment_max_chars_per_doc"]),
max_chars_total=int(system["chat_attachment_max_chars_total"]),
)
# uvicorn's default WebSocket frame ceiling. Never derive below it so chat
# behaves identically to older builds even if the configured totals are tiny.
_WS_MAX_SIZE_FLOOR = 16 * 1024 * 1024
def compute_ws_max_size(max_total_bytes: int) -> int:
"""WebSocket message ceiling that fits a full attachment batch.
Chat attachments ride the unified WS as base64 inside one JSON message
(×4/3 inflation), so uvicorn's frame cap — not the policy above — is the
binding constraint for large uploads. Add slack for the JSON envelope
(message text, metadata, quoting) on top of the inflated payload.
"""
inflated = (max_total_bytes * 4) // 3
return max(_WS_MAX_SIZE_FLOOR, inflated + 8 * 1024 * 1024)
def get_prior_image_reinject_limit() -> int:
"""How many earlier images a later turn re-attaches.
Read at call time like the attachment policy above, so a deployment can
change it without a restart, and 0 turns the behaviour off entirely.
Resolved with the seeded default rather than by subscript: a system.json
written before this key existed is the normal state of every upgraded
install, and a missing knob must not take image re-injection down with it.
"""
return _coerce_clamped_int(
load_system_settings().get("chat_prior_image_reinject_max"),
DEFAULT_SYSTEM_SETTINGS["chat_prior_image_reinject_max"],
*CHAT_PRIOR_IMAGE_REINJECT_RANGE,
)
def get_ws_max_size() -> int:
"""Frame ceiling for the current settings — wire into every uvicorn launch."""
return compute_ws_max_size(get_chat_attachment_limits().max_total_bytes)
# Idle keep-alive window for backend HTTP connections — wire into every uvicorn
# launch. The browser never reaches the backend directly: `web/proxy.ts` rewrites
# `/api/*` and Next.js forwards over Node's `http.globalAgent`, which pools idle
# sockets and reaps them on its own 5s `timeout`. uvicorn's `timeout_keep_alive`
# also defaults to 5s, so both ends armed an identical idle timer on the same
# socket and raced to close it: when the server's FIN landed on a socket the pool
# was simultaneously handing to a new request, the request died with `ECONNRESET`
# and the proxy turned it into a 500 ("Failed to proxy ... socket hang up" ->
# "Failed to load sessions" in the UI). Any value comfortably above the proxy's
# 5s reaper leaves the client as the only side that closes an idle connection,
# which is the safe direction — a pool retiring its own socket removes it before
# any request can be assigned to it, so the collision cannot happen at all.
HTTP_KEEP_ALIVE_TIMEOUT = 300
def load_auth_settings() -> dict[str, Any]:
return get_runtime_settings_service().load_auth()
def load_integrations_settings() -> dict[str, Any]:
return get_runtime_settings_service().load_integrations()
def load_mineru_settings() -> dict[str, Any]:
return get_runtime_settings_service().load_mineru()
def load_llamaindex_settings() -> dict[str, Any]:
return get_runtime_settings_service().load_llamaindex()
def load_graphrag_settings() -> dict[str, Any]:
return get_runtime_settings_service().load_graphrag()
def load_query_rewrite_settings() -> dict[str, Any]:
return get_runtime_settings_service().load_query_rewrite()
def load_lightrag_settings() -> dict[str, Any]:
return get_runtime_settings_service().load_lightrag()
def load_lightrag_server_settings() -> dict[str, Any]:
return get_runtime_settings_service().load_lightrag_server()
def load_document_parsing_settings() -> dict[str, Any]:
return get_runtime_settings_service().load_document_parsing()
def export_runtime_settings_to_env(*, overwrite: bool = True) -> dict[str, str]:
return get_runtime_settings_service().export_environment(overwrite=overwrite)
__all__ = [
"CHAT_ATTACHMENT_CHARS_RANGE",
"CHAT_ATTACHMENT_MAX_FILE_MB_RANGE",
"CHAT_ATTACHMENT_MAX_TOTAL_MB_RANGE",
"DEFAULT_AUTH_SETTINGS",
"DEFAULT_DOCUMENT_PARSING_SETTINGS",
"DEFAULT_GRAPHRAG_SETTINGS",
"DEFAULT_IMA_SETTINGS",
"DEFAULT_INTEGRATIONS_SETTINGS",
"DEFAULT_LIGHTRAG_SETTINGS",
"DEFAULT_LIGHTRAG_SERVER_SETTINGS",
"DEFAULT_LLAMAINDEX_SETTINGS",
"DEFAULT_MINERU_SETTINGS",
"DEFAULT_PAGEINDEX_SETTINGS",
"DEFAULT_QUERY_REWRITE_SETTINGS",
"DEFAULT_SYSTEM_SETTINGS",
"DOCUMENT_PARSING_ENGINE_DOCLING",
"DOCUMENT_PARSING_ENGINE_LITEPARSE",
"DOCUMENT_PARSING_ENGINE_MARKITDOWN",
"DOCUMENT_PARSING_ENGINE_MINERU",
"DOCUMENT_PARSING_ENGINE_PYMUPDF4LLM",
"DOCUMENT_PARSING_ENGINE_TEXT_ONLY",
"DOCUMENT_PARSING_ENGINE_TIKA",
"DOCLING_MODE_LOCAL",
"DOCLING_MODE_REMOTE",
"LITEPARSE_IMAGE_MODES",
"MINERU_MODE_CLOUD",
"MINERU_MODE_LOCAL",
"QUERY_REWRITE_STRATEGIES",
"SETTINGS_DERIVED_ENV_KEYS",
"ChatAttachmentLimits",
"RuntimeSettingsService",
"compute_ws_max_size",
"ensure_runtime_settings_files",
"export_runtime_settings_to_env",
"get_chat_attachment_limits",
"get_runtime_settings_service",
"get_ws_max_size",
"load_auth_settings",
"load_document_parsing_settings",
"load_graphrag_settings",
"load_integrations_settings",
"load_lightrag_settings",
"load_lightrag_server_settings",
"load_llamaindex_settings",
"load_mineru_settings",
"load_query_rewrite_settings",
"load_system_settings",
]