DeepTutor v1.3.0 Release Notes

Release Date: 2026.04.27

Highlights

Versioned Knowledge Base Indexes and Re-index Workflow

Knowledge bases now keep vector indexes per embedding configuration instead of treating one llamaindex_storage/ directory as the whole truth. Each new index version records an embedding signature and metadata, so switching models no longer has to overwrite the previous index, and switching back can reuse a ready version when the signature matches.

• Versioned storage layout — new indexes are written as flat version-N/ directories with meta.json; legacy root and nested llamaindex_storage layouts remain readable for existing installs.
• Embedding-aware reads and writes — RAG search, document additions, manager statistics, and delete/cleanup paths now resolve storage through the active embedding signature. If no ready version matches the current embedding model, retrieval returns a clear needs_reindex signal instead of failing later with an opaque storage error.
• Background re-index API — POST /api/v1/knowledge/{kb_name}/reindex rebuilds a KB against the active embedding configuration, streams logs through the existing task channel, and returns noop: true when a matching ready index already exists.
• Index status surfaced to the UI — KB summaries now include index-version metadata, active-match state, embedding mismatch flags, progress, and re-index readiness so the frontend can explain why a KB needs rebuilding.

Knowledge Management Page Rebuild

The Knowledge page has been split from a monolithic screen into a focused master-detail workspace for day-to-day KB operations.

• Dedicated KB detail tabs — Files, Add documents, Index versions, and Settings now live as separate sections with a compact header showing provider, embedding model, default status, update time, and live task status.
• Raw file browser and inline preview — the new Files tab lists documents from the KB raw/ directory and opens them in an inline preview pane, reusing the chat preview pipeline for PDFs, images, Markdown, code/text, and fallback downloads. The file list can collapse to reclaim preview space.
• Re-index controls and logs — the Index versions section shows active, stale, legacy, and inactive versions, with a one-click Re-index action and live process logs for rebuild tasks.
• Progress and history hooks — useKnowledgeBases, useKnowledgeProgress, and useKnowledgeHistory merge server state with live WebSocket/SSE progress, auto-refresh active work, and keep recent create/upload/re-index outcomes visible.

Embedding Runtime, Provider Coverage, and Dimension Discovery

The embedding stack was tightened around provider-specific behavior instead of assuming every service behaves like OpenAI's default endpoint.

• No more hard-coded 3072 default — embedding dimension now starts as unknown/empty and is auto-filled from the provider response after a successful test connection. The test probe deliberately avoids sending dimensions so it measures the model's native vector length before any Matryoshka truncation.
• Full endpoint URL semantics — httpx-based embedding adapters now treat EMBEDDING_HOST / catalog URLs as the exact endpoint to call, while the new openai_sdk adapter keeps SDK-style /v1 base URL behavior. .env.example documents concrete endpoint examples for OpenAI, Cohere, Jina, Ollama, SiliconFlow, and Aliyun DashScope.
• New embedding adapters and bindings — added official OpenAI SDK embedding support, Aliyun DashScope native multimodal embeddings, SiliconFlow presets, OpenRouter/custom OpenAI-SDK profiles, provider batch limits, multimodal provider flags, and per-provider API-key fallbacks.
• Multimodal embedding requests — EmbeddingRequest now accepts structured contents plus DashScope enable_fusion; Cohere v2, Jina, OpenAI-compatible gateways, and DashScope handle multimodal payloads through their own adapter rules.
• Better provider errors — embedding failures now preserve provider status, body, model, and URL context, with clearer handling for 4xx responses and non-JSON/HTML gateway replies.

LLM Reasoning Streams and Vision Attachment Robustness

Reasoning traces and image attachments now flow through more provider paths with less provider-specific surprise.

• Reasoning deltas — on_reasoning_delta is wired through the base LLM provider contract, OpenAI-compatible streaming, Azure SDK streaming, Anthropic paths, and OpenAI Responses parsing. Streaming output wraps reasoning text in <think>...</think> before normal content resumes.
• DeepSeek reasoning defaults — DeepSeek reasoning model patterns can auto-inject a high reasoning effort when the caller has not specified one, matching providers that require an explicit switch to surface thinking output.
• Vision URL capability flags — provider/model capabilities now distinguish "supports vision" from "accepts image URLs." Moonshot/Kimi vision models and Anthropic-style adapters force local attachment URLs into inline base64 when possible.
• Local attachment URL resolution — /api/attachments/... image URLs can be resolved back through the attachment store and sent as base64 to providers that reject remote URL form; unresolved external URLs are counted as dropped image inputs instead of silently pretending they were sent.

Space Hub, Skills Tags, and Personal Library UX

Personal learning artifacts have been gathered under a new Space area in the sidebar.

• Space navigation — /space redirects to /space/notebooks and the new mini-nav groups Notebooks, Question Bank, Skills, and Memory with a shared section header style.
• Notebooks section — notebooks can be created, deleted, searched, opened, and inspected with rendered record previews. Saved TutorBot, chat, research, and Co-Writer outputs receive distinct badges and can link back to the original chat session when metadata is available.
• Question Bank section — quiz entries can be filtered by all/bookmarked/wrong-only, grouped with categories, renamed, removed from categories, bookmarked, deleted, and opened back in their source context.
• Memory section — the Memory page moves into Space with edit/preview modes for summary and profile, manual save, refresh-from-session, clear actions, unsaved-change status, and localized feedback.
• Skills section — user-authored skills now support tags in frontmatter plus a .tags.json vocabulary. The API adds tag list/create/rename/delete endpoints, and the UI can filter by tag, manage tags, rename skills, and edit tag assignments while preserving the existing SKILL.md workflow.

Dependency Layers, TutorBot Debugging, and Windows Startup

The install story has been reorganized around pyproject extras, with requirements files kept as mirrors for Docker/CI environments. This also makes TutorBot setup and channel debugging less ambiguous: the agent engine, channel SDKs, Matrix native dependencies, and core server provider imports now live in clearly separated layers.

• Extras hierarchy — .[cli] now includes RAG, document parsing, and built-in provider SDKs; .[server] builds on CLI with FastAPI/uvicorn; .[tutorbot], .[matrix], .[math-animator], .[dev], and .[all] layer optional capabilities explicitly.
• TutorBot dependency boundary — requirements/tutorbot.txt now mirrors .[tutorbot], depends on server.txt, and keeps channel/agent dependencies such as cron, MCP, Telegram, Feishu/Lark, DingTalk, Slack, QQ, Socket.IO, socks, and message-pack tooling in the TutorBot layer instead of mixing them into the base install.
• Matrix channel split-out — Matrix / Element support has its own .[matrix] extra and requirements/matrix.txt, with matrix-nio[e2e], Markdown sanitization helpers, and explicit libolm setup notes for native encryption dependencies.
• Runtime dependency fix (#391) — loguru and json-repair moved into the server dependency layer because provider-core imports need them before TutorBot is involved. This fixes clean server installs that previously crashed on missing modules.
• Windows launcher robustness (#391, #398) — scripts/start_web.py now reads backend/frontend subprocess output as UTF-8 with replacement, avoiding UnicodeDecodeError on Windows locales such as GBK.
• Docs and CLI hints — README, Chinese README, CLI README, and CLI error messages now point users to pip install -e ".[cli]" / pip install -e ".[server]" instead of older requirements-first commands. A new requirements/matrix.txt mirrors the Matrix extra and documents the native libolm prerequisite.

Bug Fixes

• Knowledge upload/create diagnostics (#392, #405) — KB initialization, upload, and re-index tasks now propagate failure details and stack traces through task logs; the UI can show richer errors instead of appearing to do nothing when background ingestion fails.
• KB name validation — HTTP and CLI creation paths now reject path-like or URL-reserved characters while preserving Unicode-friendly names, preventing invalid KB folders and unsafe routes.
• Case-insensitive document discovery — KB directory scanning and CLI document collection now use the shared file router, so uppercase extensions such as .PDF and .MD are accepted consistently.
• Safer document filenames — uploaded filenames are normalized, path fragments are stripped, and extensions are lowercased before validation and storage.
• Raw file serving safety — KB raw-file endpoints resolve paths strictly under the raw/ directory and reject traversal attempts.
• Model catalog environment overlay — .env values are only synced into the catalog while it still looks pristine, avoiding accidental overwrites once users have multiple custom profiles.
• Research reporting fallback (#404) — the reporting agent's JSON-fallback warning now uses an f-string so loggers that do not apply % formatting still include the section title cleanly.

Test Suite Expansion

• Knowledge/RAG — new coverage for KB naming, index-version allocation and read priority, legacy-to-flat storage compatibility, LlamaIndex storage layout, raw directory initialization, case-insensitive file routing, KB deletion, and API upload edge cases.
• Embedding/config — new tests cover dimension auto-fill from test probes, catalog .env overlay behavior, DashScope and OpenAI SDK adapters, Qwen3 send_dimensions, URL transparency, non-JSON provider responses, and multimodal embedding requests.
• LLM/multimodal — new tests validate reasoning/vision capability behavior and local attachment URL conversion for providers that require inline base64 images.
• CLI and validation — CLI KB collection and document validator tests cover uppercase extensions, Chinese filenames, and Windows-style path stripping.

Community Contributions

• @jonathanzhan1975 — Fix Windows server startup and missing server runtime dependencies affecting clean Web/TutorBot installs (#391)
• @kagura-agent — Clean up reporting-agent fallback logging for JSON parse failures (#404)

Recent open discussions after v1.2.5 also shaped this release window, especially KB upload/create failures (#392, #405), TutorBot Agent restart/state reports (#385), Windows startup reports (#398), dependency-installation pain (#402), JSON robustness feedback (#400), and the next wave of Space/Memory/project organization requests (#397, #401, #403).

Full Changelog: v1.2.5...v1.3.0