DeepTutor v1.2.3 Release Notes

Release Date: 2026.04.24

Highlights

Document Attachments in Chat

Chat now accepts non-image file attachments (PDF, DOCX, XLSX, PPTX) alongside images. A new paperclip button in the composer opens a system file picker, and drag-and-drop / paste have been extended from images-only to all supported document types. Attached documents are rendered as typed preview cards (colour-coded icon + filename + size label) in both the pending-attachment bar and the message history. On the backend, a new document_extractor module extracts plain text from the uploaded bytes using PyMuPDF / pypdf / python-docx / openpyxl / python-pptx (all optional, graceful fallback) and injects the content into the [Attached Documents] section of the effective user message, so the LLM can read the file without a separate RAG call. File-type classification, per-file and total size limits, and duplicate-name detection are handled by web/lib/doc-attachments.ts on the frontend and DocumentValidator on the backend.

Model Thinking Block Display

Responses from reasoning models (DeepSeek-R1, Claude with extended thinking, QwQ, etc.) often contain <think> / <|thinking|> scratchpad blocks that were previously rendered as raw text. A new parseModelThinkingSegments parser (web/lib/think-segments.ts) splits assistant content into alternating text and thinking segments, and AssistantResponse now renders each thinking segment as a collapsible ModelThinkingCard — collapsed by default — so users can peek at the model's chain-of-thought without the scratchpad overwhelming the conversation. Incomplete (still-streaming) thinking blocks show a pulsing indicator and expand automatically.

Tri-State send_dimensions for Embeddings (#368)

Some OpenAI-compatible embedding providers reject the dimensions parameter that OpenAI's text-embedding-3-* models require. A two-part fix: first, the adapter now only sends dimensions when the model name matches text-embedding-3* (PR #368 by @jefflv). Second, a new Send Dimensions tri-state toggle (Auto / On / Off) was added to the Settings page, the .env store (EMBEDDING_SEND_DIMENSIONS), and the model catalog, giving operators explicit control. Auto (the default) preserves the #368 heuristic; On forces the parameter for providers that accept it on custom models; Off suppresses it unconditionally. The toggle is reflected end-to-end: catalog → provider_runtime.ResolvedEmbeddingConfig.send_dimensions → OpenAICompatibleEmbeddingAdapter.

LLM Provider Core Refactor

The monolithic factory.py has been rewritten around a new provider_core/ package (~3 000 lines) that gives each provider family its own module: openai_compat_provider, anthropic_provider, azure_openai_provider, github_copilot_provider, and openai_codex_provider, all inheriting from a shared BaseProvider. A provider_factory.py resolves the correct runtime provider from config, and factory.py itself shrank from ~600 to ~490 lines by deriving presets dynamically from the PROVIDERS registry instead of maintaining hard-coded dictionaries. A new context_window.py module exposes resolve_effective_context_window(), used by ContextBuilder to base the history-budget calculation on the model's true context window rather than the max_tokens output cap — improving long-conversation history recall for models with large windows.

Soul Template Editor (PR #373)

TutorBot's "Soul" (system personality) can now be authored directly inside the Agents page. The new inline editor lets users create, preview, and save SOUL.md templates with YAML frontmatter, replacing the previous workflow of hand-editing files on disk. Contributed by @srinivasrk.

Co-Writer Save to Notebook

The Co-Writer toolbar gains a Save to Notebook button (📓 icon). Clicking it opens the existing SaveToNotebookModal with a new co_writer record type, so Co-Writer drafts appear alongside chat and quiz entries in the Knowledge page's Notebooks tab. Backend: co_writer was added to the notebook record type enum, the summarize agent prompts, and the API Literal type.

Knowledge Base Management Improvements

• Drag-and-drop upload — the Knowledge page now accepts file drops directly onto KB cards (or the creation form) with real-time extension/size validation, duplicate-name detection, and a typed file-selection list before upload starts.
• /supported-file-types endpoint — a new REST endpoint returns the server's current upload policy (accepted extensions, per-file and per-PDF size caps) so the web client stays in sync without hard-coding.
• Richer KB cards — each card now displays creation / last-updated timestamps, embedding model name, dimension, reindex-needed badge, and live progress bars with percent readout during indexing.
• Delete resilience (#370) — shutil.rmtree now uses an onerror handler that clears the read-only bit and retries, preventing Docker bind-mount and Windows permission errors from leaving a KB stuck in the list.
• Progress persistence — ProgressTracker now writes a snapshot file alongside the kb_config.json entry and emits task-stream events, so WebSocket subscribers and page reloads can recover live indexing state without relying on in-memory callbacks. When a KB reaches ready, the progress blob is removed from config to keep the card looking like a stable resource.

Question Generation Language Fidelity

Extracted the language-directive system from the Book engine's _language.py into a shared services/prompt/language.py module. The Deep Question agents — Generator, IdeaAgent, and FollowupAgent — now call append_language_directive() on their system prompts, ensuring that quiz questions, answer choices, and follow-up answers respect the user's configured language instead of occasionally drifting to English.

Settings Page Tour Redesign

The Run Tour button moved from the page bottom to the top toolbar, sitting alongside Save Draft and Apply. The guided tour itself was expanded to walk through the full save-and-test cycle (Save → Diagnostics → Apply). The former bottom area was replaced with a concise configuration note explaining the runtime priority of model_catalog.json over .env.

CLI: Notebook add-md and replace-md

Two new deeptutor notebook sub-commands let users add or replace Markdown content in a notebook record directly from the terminal, useful for scripted workflows and CI pipelines.

Bug Fixes

• TutorBot pure-CJK bot name crash — creating a bot whose name contains only non-ASCII characters produced an empty slug, breaking the API route. A stable ASCII fallback (bot-<hash>) is now generated, and the frontend surfaces a creation error toast instead of silently failing.
• React 19 I18nProvider render-time setState warning — i18n.init() was being called synchronously during the first render of I18nProvider, triggering a React 19 warning about state updates in the render phase. Initialization is now performed at module-load time; the provider body only syncs document.documentElement.lang via useEffect.
• Skills default to off — skillsAutoMode now defaults to false so new users aren't surprised by automatic skill injection until they intentionally enable it.
• Moonshot default Base URL — changed from https://api.moonshot.ai/v1 to https://api.moonshot.cn/v1 to match the provider's current canonical endpoint, with all multilingual README files updated.
• Version badge display — fixed a minor rendering issue in the sidebar version badge introduced during the v1.2.2 merge.

Provider Registry Enhancements

• custom_anthropic — a new provider spec for Anthropic-API-compatible endpoints (e.g. AWS Bedrock proxies) that routes through the Anthropic backend instead of OpenAI-compat.
• thinking_style — new ProviderSpec field allowing providers like Volcengine to advertise how they signal extended-thinking mode.
• Alias expansion — lm-studio, anthropic-compatible, openai-compatible (hyphenated) are now recognized; canonical_provider_name() uses to_snake() for more robust normalization.

Test Suite Expansion

Net +1 900 test lines across 15 new or expanded files: test_document_extractor.py (245), test_language_prompts.py (156), think-segments.test.ts (122), test_provider_runtime.py (103), test_llm_probe_config.py (116), test_manager_delete.py (79), doc-attachments.test.ts (75), test_context_window_detection.py (60), test_progress_tracker.py (58), quiz-question-type.test.ts (58), plus expansions to test_factory_provider_exec.py, test_context_builder.py, test_chat_params_config.py, test_config_module.py, test_knowledge_router.py, and test_start_tour.py.

What's Changed

• fix(embedding): gate dimensions for text-embedding-3 models by @Jeff-Lv in #368
• feat: Revamp soul template creation and usage by @srinivasrk in #373
• feat(cli): add add-md and replace-md commands to notebook group by @zbinxp in #371

New Contributors

• @Jeff-Lv made their first contribution in #368
• @zbinxp made their first contribution in #371

Full Changelog: v1.2.2...v1.2.3