DeepTutor v1.4.0 Release Notes

Release Date: 2026.05.22

v1.4.0 is the GA cut of the v1.4 line. It carries the full v1.4.0-beta scope
(Auto Mode, three-layer Memory workbench, agentic Deep Research / Deep Solve /
Question, LlamaIndex chat refactor, unified capabilities infrastructure +
i18n, Visualize/Animator merge, new chat tools, settings split, multi-user
isolation hardening, and the deeptutor start / deeptutor init launcher)
and adds a focused set of agent-engine and runtime hardening fixes on top.
For the full beta scope see v1.4.0-beta.

What's New Since v1.4.0-beta

Reasoning Effort + Provider Thinking Flags

The agentic engine now normalizes "reasoning effort" across providers in one
place, instead of each pipeline re-deriving it.

• build_provider_extra_kwargs in deeptutor/core/agentic/client.py
  resolves reasoning_effort against provider_registry, maps minimal /
  minimum to the right wire shape (DashScope uses minimum), and routes
  the on/off intent through provider thinking-style toggles —
  thinking_type (DeepSeek), enable_thinking (Qwen-style), or
  reasoning_split. Known reasoning models default to high; the
  deepseek-v4-flash shape gets thinking disabled by default.
• LLMClientConfig.reasoning_effort is plumbed end-to-end. All four
  pipelines — agentic chat, question, research, solve — pass the binding +
  effort into build_completion_kwargs, so a single user-level setting
  controls reasoning behavior across capabilities.

Tool-Schema Fallback For Strict Providers

Some OpenAI-compatible providers reject native function-calling schemas with
a non-standard error. run_labeled_step now detects that case, strips
tools / tool_choice from the request, retries once, and emits a warning
progress event so the user knows the call ran in tool-less prose mode.
Behavior is unchanged for providers that accept tool schemas normally.

Restart-Safe Turn Runtime

A server or container restart used to leave the database row for an
in-flight turn stuck on running, blocking the next message in that
session and leaving the UI hanging on an event stream that would never
complete.

• Orphan detection — TurnRuntimeManager now checks whether this
  process still owns the turn's in-memory runner. If not, the persisted
  turn is marked failed with "Turn interrupted by server restart. Please retry your message."
• start_turn sweeps stale active turns for the session before
  creating a new turn, so the user can immediately retry after a restart.
• subscribe_turn synthesizes a terminal error + done event for
  the orphaned turn so the frontend cleanly closes its streaming state
  instead of waiting indefinitely.

Frontend API Base — Docker Placeholder Hardening

web/lib/api.ts switched from exact-match to substring-token detection of
the NEXT_PUBLIC_API_BASE placeholder, and exposes isApiBasePlaceholder()
for reuse. This survives small changes to the Docker placeholder shape that
previously slipped through and produced a blank Settings page with no
visible error. The unused auto-generated web/.env.local shipped with the
beta is removed.

LLM Config Probe — Clearer Status Copy

The /settings/llm probe now emits an explicit "Basic LLM completion
succeeded. Chat additionally validates streaming and provider tool
compatibility at runtime." line after the smoke completion, so users know
the probe deliberately doesn't cover the streaming / tool-call paths that
chat exercises.

CLI Chat REPL — Config Surface Aligned With Docs

The deeptutor chat REPL surface was tightened so it matches the public
docs at deeptutor.info.

• deeptutor chat --config key=value and --config-json '<json>' seed
  the initial config without entering the REPL first.
• /config set key value and /config set key=value are both accepted;
  JSON values ([…], {…}) are parsed correctly via shlex.
• Backslash-continuation lets you send multi-line prompts in one turn.
• /refs prints a structured state snapshot (session, capability, tools,
  KB, history, notebooks, language, config) instead of a single dim line.
• deeptutor plugin info <name> now also returns cli_aliases and the
  capability availability block.

Repo & Docs Hygiene

• New issue template for the public docs site (.github/ISSUE_TEMPLATE/docs.yml).
• AGENTS.md modernized to reflect Auto Mode, tool gating, and the
  current capability stages.
• .gitignore covers .playwright-cli/; stale .playwright-cli/
  captures, .env.example_CN, and DeepTutor.code-workspace removed.

Tests

• New tests/core/test_agentic_client_provider_kwargs.py covering the
  reasoning-effort + provider thinking-style matrix.
• New tests/core/test_labeled_step_tool_fallback.py exercising the
  tool-schema retry path end-to-end against a scripted client.
• tests/services/session/test_turn_runtime_subscribe.py adds coverage
  for orphan-running-turn recovery on both subscribe and start_turn.
• tests/cli/test_chat_cli.py adds REPL config/backslash tests and a
  plugin-info contract check.
• New tests/cli/test_docs_contract.py keeps the public site docs in
  sync with the CLI surface (links + deeptutor … examples).
• tests/scripts/test_docker_compose.py + web/tests/api-resolve-base.test.ts
  cover the new placeholder detection.

Upgrade Notes

• From v1.4.0-beta: drop-in. PyPI installs with pip install -U deeptutor
  (PyPI normalizes 1.4.0 over 1.4.0b0). Docker users pull
  ghcr.io/hkuds/deeptutor:latest.
• Reasoning effort is now read from LLMConfig.reasoning_effort. If
  you previously set provider thinking flags manually in extra_body,
  the agent will still respect them, but the recommended path is to set
  reasoning_effort and let the engine map it.
• Restart recovery is automatic. After upgrading, any existing
  database rows stuck on running from previous crashes will be
  finalized the next time their session is opened.
• Beta artifact cleanup: web/.env.local was auto-generated by the
  legacy launcher and is no longer needed. If you rebuilt the frontend
  manually with that file, delete it before the next build.

Full Changelog: v1.4.0-beta...v1.4.0