DeepTutor v1.3.1 Release Notes

Release Date: 2026.04.28

v1.3.1 is a stability release after v1.3.0. It focuses on safer RAG routing,
stronger embedding validation, more reliable Docker/TutorBot restarts, and a
set of small but important Web UX fixes.

Highlights

Safer RAG and Knowledge Base Routing

• Selected KB is now trusted system state - chat RAG calls no longer let the
  LLM invent or override kb_name; the model only sees a query, and DeepTutor
  routes it to the KB selected in the UI/session.
• No silent fallback when RAG has no KB - if RAG is enabled but no KB is
  selected, the turn skips KB retrieval with a clear progress message instead
  of accidentally querying stale/default state.
• Default KB aliases are handled consistently - default, current,
  selected, and Chinese equivalents resolve to the configured default KB for
  tool calls, file listing, and re-index APIs, while a real KB named default
  still wins over the alias.
• Incremental document adds use the service layer - adding files now goes
  through RAGService.add_documents, keeping add/search/re-index behavior on
  the same provider and index-version path.
• RAG internals are easier to maintain - the LlamaIndex pipeline was split
  into focused modules for loading, embedding, storage, errors, and orchestration;
  smart multi-query retrieval now lives in SmartRetriever.

Embedding and Index Reliability

• Embedding responses are validated before use - DeepTutor now rejects
  dropped vectors, null values, non-numeric values, non-finite values, and
  inconsistent dimensions before they reach LlamaIndex.
• Connection tests probe batch behavior - embedding smoke tests now send a
  tiny batch, catching providers that only return one vector or change
  dimensions between inputs.
• Bad indexes fail with actionable messages - null-vector or shape mismatch
  retrieval failures now return a re-index hint instead of exposing low-level
  NoneType * float style errors.
• Index status is less noisy during writes - empty in-progress version
  directories no longer mark brand-new KBs as needs_reindex, and failed empty
  version folders are cleaned up when possible.
• Embedding examples were clarified - services/embedding/.env.example
  now documents full endpoint URL semantics and concrete provider examples for
  OpenAI, SiliconFlow, Ollama, Cohere, Jina, vLLM, Azure OpenAI, DashScope, and
  OpenAI-SDK-style gateways.

Docker, Memory, and TutorBot Runtime

• Docker images can expose the app version - APP_VERSION is passed through
  to both backend and frontend runtime environment variables.
• Shared memory has its own Docker volume - compose files now mount
  ./data/memory:/app/data/memory; README persistence docs were updated.
• Memory migration is safer - legacy SUMMARY.md and PROFILE.md files are
  copied into data/memory even when the target directory already exists, while
  existing target files are preserved.
• Memory refreshes are serialized - concurrent profile/summary rewrites now
  run under a lock to avoid racing writes.
• TutorBot restart intent is preserved - graceful server shutdown keeps each
  bot's auto_start flag intact for the next Docker/host restart, while manual
  stops still disable auto-start.
• TutorBot shares long-term memory - started bot agents now receive the
  shared memory directory instead of running without it.

Web and Authoring UX Fixes

• IME-safe message sending - chat composers no longer submit when Enter is
  being used to confirm Chinese/Japanese/Korean IME candidates.
• Knowledge list stays fresh in chat - the chat page reloads KB metadata on
  focus, page show, and visibility changes, so newly created or re-indexed KBs
  appear without a full refresh.
• Markdown preview protects pseudo-tags - unknown HTML-like tags such as
  <think> are escaped for display while preserving source line counts for
  editor/preview sync.
• Co-Writer output strips reasoning tags - closed, aliased, attributed, and
  unclosed <think> / <thinking> blocks are removed from final edit output.
• Theme initialization runs before hydration - the theme script is rendered
  from the server so dark/light preference is applied before React hydrates.
• Knowledge UI feedback is clearer - index version chips have cleaner labels,
  failed empty active indexes are explained, and 404s from newer UI vs older
  Docker backend now suggest pulling/recreating the container.
• Memory page feedback is clearer - refresh calls distinguish "checked, no
  long-term updates" from real failures.

Startup and Windows Robustness

• CLI/server streams tolerate legacy code pages - startup scripts and API
  runners use replacement-safe text streams to avoid Unicode crashes on Windows
  locales such as GBK/CP936.
• Child processes inherit safer encoding - web/tour startup paths set
  PYTHONIOENCODING=utf-8:replace.
• Generated frontend env files are UTF-8 - start_web.py now writes
  web/.env.local with explicit UTF-8 encoding.
• GHCR compose pulls fresher images - docker-compose.ghcr.yml now uses
  pull_policy: always for the published image.
• Docs/locales were refreshed - README persistence notes were updated, the
  Polish README link was added, and English/Chinese UI copy gained missing
  labels for knowledge, memory, TutorBot soul templates, and Co-Writer drafts.

Tests

• Added/updated coverage for chat RAG KB routing, default KB aliases, knowledge
  file/re-index APIs, embedding batch validation, LlamaIndex invalid-vector
  failures, in-progress index-version status, incremental add storage layout,
  TutorBot auto-start/shared memory, memory migration, Windows CLI encoding,
  IME keyboard handling, markdown tag escaping, and reasoning-tag cleanup.

Upgrade Notes

• Docker users should pull and recreate the container so the Web UI and backend
  knowledge APIs stay in sync.
• If a KB was indexed with a broken or changed embedding provider, use
  Re-index from the Knowledge page after fixing the embedding settings.
• If you persist data manually, add the new shared memory mount:
  ./data/memory:/app/data/memory.

Full Changelog: v1.3.0...v1.3.1