DeepTutor v1.5.17 Release Notes

Release Date: 2026.08.25

v1.5.16 connected a MarginNote library and put a run of gateway failures to rest. This one changes who a Partner belongs to: they stop being a deployment-wide resource only an admin can touch and become something each member builds, owns, and holds their own private conversations with — an admin still lends theirs out through grants. Around that sit a knowledge base that tracks GitHub repositories, Antigravity CLI under My Agents, a WeChat QR code drawn in the browser instead of a log file, and a container that keeps the optional extras you declared. Existing partners keep working and migrate themselves; the one behavior change is scoped to non-admin users, who can now see a Partners page that used to be closed to them.

What's New

Partners belong to people, not to the deployment

Every /api/v1/partners route used to sit behind a blanket admin gate, so a member could talk to a partner an admin had assigned them and nothing else. Three rights now nest instead: manage (its creator, plus any admin) covers soul, channels, models, assets, lifecycle and deletion; use adds anyone an admin assigned it to, and means holding a conversation; anyone else cannot see that the partner exists — an unowned partner and an invisible one answer alike, so ids cannot be enumerated.

Conversations follow the human, not the partner. Two people talking to the same companion never see each other's threads, and each side reads back in the web app under its own account. Grants still exist and are unchanged in shape, but they now only offer admin-managed partners: one someone built for themselves is theirs to share or not, since its SOUL.md is usually written personally.

A chat account can carry your DeepTutor identity

A partner reached over QQ or Telegram used to know only a channel-local sender id, so every inbound message was anonymous — it landed in the shared thread pool, and the partner answered out of the admin workspace rather than the sender's own library. Ask your partner for a code in the web app, send /link <code> to it from the chat account you want connected, and from then on that sender is you: the conversation is private to your account, readable back in the browser, and the partner reads your knowledge, notebooks and memory the way it would in a web turn.

Two partners can share a channel

Channel runtime state — bot tokens, long-poll cursors, conversation references, E2EE device stores — lived in one directory per channel, not per partner, so two partners configured on the same channel read each other's credentials and overwrote each other's cursor. Only one of them could ever be online. State now lives under data/partners/<id>/channels/<channel>/, and the old tree is copied across on first start when its owner is certain — the saved token matches one partner's configured token, or only one partner has that channel enabled at all. A genuine tie re-authenticates once rather than being handed someone else's account.

Personal WeChat signs in from the browser

The QR-code exchange has always worked, but it only ran from the channel's own start() and drew the code on the server's stdout — which on any container deployment is a supervisord log the person configuring the partner cannot reach (#951). The same exchange now runs for the web app: press Scan to connect on the partner's channel page, scan, and the bot token is written into the channel config server-side. A status reply says whether the login succeeded, never what it produced. The terminal still prints a code as a fallback.

A knowledge base can track GitHub repositories

Register a repo, branch and glob as a GitHub source and its Markdown is pulled into the KB and re-synced on demand, so documentation you follow stays current without re-uploading it. Contributed as #903; download destinations are contained inside the KB's raw/ directory, since a .. segment or an absolute path in a tree entry would otherwise have written — and, on the removal branch, deleted — outside the base.

Antigravity CLI joins My Agents

Google retired Gemini CLI in June and pointed its users at Antigravity CLI, so anyone on a Google AI Pro/Ultra or Gemini Code Assist plan was left with a gemini backend that had no CLI to detect (#828). agy is now a backend of its own — connect it, consult it mid-turn, resume its conversations. The Gemini CLI backend stays: it still runs for anyone holding a Gemini API key, and a working connection must not break on upgrade.

deeptutor doctor

One command that answers "is this workspace ready to start a session?" — settings, providers, dependencies, ports. --online also sends a small request to the configured model provider; --format json prints the same report for a script or an agent. Contributed as #959.

Containers keep the extras you declared

A container is disposable, so docker exec … pip install ".[partners]" survives exactly until the next compose down (#762). Declare them on the deployment instead — DEEPTUTOR_EXTRAS: "math-animator,partners", and DEEPTUTOR_APT_PACKAGES for system libraries — and every container started from it re-applies them. A warm container pays one metadata lookup per requirement, the pip cache lives on the data volume, and a missing wheel leaves that one feature unavailable rather than taking the deployment down.

Embeddings survive a rate-limited provider

Reindexing a large library against a low-RPM provider used to burn hours and then die on a 429. Three things changed: a key pool rotates across provider × model with per-key cooldown so one throttled key no longer poisons the run; a retry budget waits out Retry-After instead of exhausting itself on a sliding window; and a process-wide throttle serializes the interval-plus-post across concurrent reindexes, which is what made a request that succeeded by hand fail inside the app. Contributed as #962.

Windows

MinerU parsing decoded its subprocess output with the platform default — GBK on a zh-CN install — and died on the first non-ASCII byte; its multi-threaded PDF renderer separately corrupted the heap. Both are fixed, the render guard scoped to Windows only (#844). Atomic writes now retry a transient PermissionError from an antivirus or indexer holding the target, and code execution works on a Windows host (#964).

Assorted

• Reasoning effort is per conversation. The model-level control from v1.5.9 can now be overridden for a single chat (#641, contributed as #958).
• Indexing fails bounded instead of hanging. A provider that accepts an embedding request and never completes it stalled the executor future forever; a heartbeat guard now raises after a bounded window of no progress (#946).
• MinerU page-layout blocks stop being indexed as content. Headers, footers and page numbers are filtered before ingest; an unrecognized block type is indexed rather than failing the whole run, so a MinerU release that adds one cannot break indexing (#949).
• Voice transcription accepts what Chrome records. audio/webm;codecs=opus is normalized once, at the wire boundary, instead of being rejected as an unknown format (#945).
• Mastery quiz cards no longer land below the fold. The viewer mounts after the post-stream scroll window closed (#960), and a quiz whose options repeat a label or an answer is rejected at registration rather than shown as an unanswerable card (#956).
• A learning path keeps its name. Three surfaces each derived it from the first module, so rebuilding a map renamed the path and the three could disagree; one function answers now, and derivation is the fallback, never the record.
• A tool that changes what the round operates on runs first. Switching mastery path mid-round left the other calls bound to the state the round started with; the dispatcher now runs rebinding tools, re-binds everything else, then runs pausing tools last.
• Local LightRAG answers cite their sources (#754), and the local LlamaIndex pipeline no longer freezes its progress-bar decision at import time (#864).
• Azure OpenAI accepts the endpoint the portal hands you. A classic …/openai/deployments/<name>/chat/completions URL is reduced to the /openai/v1 surface, so chat stops answering 404 Resource not found while the settings probe passes.
• Gemini embeds images where the model supports it, and refuses contents for one that does not rather than posting parts the endpoint will reject (#814).
• A page can ask whether a capability is installed. Plugin-served capabilities such as the Whisper practice room were offered by a stock install that could not honour them, and the turn came back Unknown capability (#963).
• The standalone CLI package declares what it actually imports (#954).

Upgrade Notes

pip install -U deeptutor; Docker users pull ghcr.io/hkuds/deeptutor:latest. No re-index and no manual migration.

• Non-admin users gain a Partners page. On a multi-user deployment members can now create and manage their own partners, and their conversations with any partner are private to their account. Existing partners have no owner_id and therefore read as admin-managed — exactly what they were — so nothing you have configured changes hands.
• Channel state moves per partner, by copy. On first start, state under data/partners/<channel>/ is copied to data/partners/<id>/channels/<channel>/ when its owner is unambiguous. The legacy tree is left untouched, so a bad outcome is recoverable by hand; a partner whose ownership was ambiguous simply re-authenticates once.
• Grants only list admin-managed partners now. A partner a member built for themselves will not appear in the assignable pool.
• Container extras are opt-in. Nothing changes until you set DEEPTUTOR_EXTRAS in your Compose file. Preview one with python scripts/install_extras.py --dry-run "<name>".
• Gemini CLI connections keep working. Antigravity is an additional backend, not a replacement.

Full Changelog: v1.5.16...v1.5.17

DeepTutor v1.5.16 Release Notes

Release Date: 2026.08.22

v1.5.15 added a capture inbox under the Book reader and, in doing so, stopped its pages from turning. That is fixed here, alongside a new connected knowledge source — a MarginNote 4 library that its own add-on fills — and a run of failures that were only reachable through a particular gateway: tool-call ids that grew until the provider refused them, embeddings rejected for a parameter we deliberately omit, and a temperature limit that only applied if you had named the right binding. Drop-in — no migrations, nothing to re-index.

What's New

MarginNote 4 as a knowledge base

Connect a library and the MN4 add-on pushes your notes, excerpts, cards and mindmap nodes into it — no upload, no index, nothing copied out of MarginNote. Pair a device from the library's Devices tab, paste the one-time token into the add-on, and syncs arrive incrementally into a store DeepTutor owns.

A turn on that library runs on seven tools of its own rather than on rag: search across excerpt and note text, read a single object, list by type, walk a document's children, follow links, filter by tag, and read mindmap cards. The chat loop hands the turn to them the way it does for an Obsidian vault, because a library that holds no index has nothing for retrieval to chunk.

Contributed as #931 by @evan188199-tech. This is phase one — read-only navigation; write-back is planned.

Book pages turn again

The capture inbox landed as a second child of the reader's flex row without making that row a flex column, so PageReader's h-full collapsed to auto: the body stopped scrolling and the page-turn footer was clipped out of view entirely. A one-line layout fix; every gate we run was green through the regression, since nothing here is visible to types or tests.

Streamed tool-call ids stop growing

A router in front of an OpenAI-compatible provider may re-send the whole tool-call id on every delta chunk. Three core sites appended it instead of assigning it, so the id grew one copy per chunk — #937 saw 47,241 characters — and past the provider's 64-character ceiling every round died with Invalid 'messages[i].tool_calls[0].id': string too long, surfacing as "I could not produce a useful response from the model output." name had the identical defect at both sites, latent on that gateway and fatal on any that repeats the name. The three sites now share one accumulator: id and name arrive whole and are assigned, arguments arrives in fragments and is concatenated.

Model limits follow the model, not the route

Kimi models lock temperature server-side and reject an explicit value with HTTP 400. The override for that has existed since before v1.5.5, but it was resolved from the configured binding's spec — so it never fired for #938, who did the ordinary thing and pointed binding="openai" at Moonshot. The route is not what enforces the limit, so the route no longer decides: the configured spec wins when it says something about the model, otherwise the model's own vendor spec answers. Every model-intrinsic override was being lost the same way behind a generic binding.

Embeddings recover from a gateway that demands encoding_format

ModelScope reads a missing encoding_format as '' and refuses the request (#934); SiliconFlow refuses it when the field is present, which is why we omit it. The same Qwen3-Embedding weights are served on both sides of that disagreement, so no default and no model-family rule can satisfy both. The happy path is byte-identical — the field is still omitted — and a 400 that names both the parameter and the value we are about to send earns exactly one retry with encoding_format="float".

Images in an index describe in parallel

The LlamaIndex pipeline described extracted images one at a time. They now run concurrently with a per-image timeout and a progress line, tunable via image_description_concurrency (default 4) and image_description_timeout_seconds (default 60). A model that turns out not to accept images is no longer retried without them — the image is the question there, and a description invented from the text around it would be indexed as fact. Contributed as #933.

LightRAG converges instead of hanging

Transport failures against a LightRAG base are now classified before they are retried: retryable HTTP statuses get up to three bounded attempts with a capped Retry-After, anything else fails immediately, and the two retry layers no longer multiply. Cancellation cleans up rather than leaking, and a Codex transport failure propagates instead of being swallowed. Contributed as #940.

Assorted

• Indexing progress lines are translatable. All 22 producers sent hardcoded English to the log box. The wire now carries the template plus its values and the frontend renders it in your language; consumers without i18n — logs, snapshots, the CLI — read exactly what they read before.
• A deleted knowledge base stops haunting your sessions. Its name lingered in each session's context chips (#936).
• The development Docker image has a frontend again. Its supervisor ran node scripts/dev.mjs against a production standalone bundle that contains no sources, no configs and no scripts/, so docker compose -f docker-compose.dev.yml up came up dead (#906). The stage now takes the builder's whole web/ tree. The production image was never affected.
• A provider's rejection body is capped before it reaches the log. That log exists so you can attach deeptutor.jsonl to a bug report, and some providers echo the rejected request — schemas, sometimes messages — back into it (#930).
• Two MarginNote libraries can no longer claim one store. "My Lib" and "My/Lib" both derive My_Lib.db; registration now rejects the collision by name, and deleting a library removes the store we created for it.
• The MN4 device bridge checks the credential first. /sync and /heartbeat resolved their store before validating the token, so an unauthenticated POST created a database per distinct header value — and pairing wrote into the caller's workspace while the device path read the default one, which could 403 every sync forever.

Upgrade Notes

pip install -U deeptutor; Docker users pull ghcr.io/hkuds/deeptutor:latest. No schema changes, no re-index, no migration.

• A MarginNote 4 library starts empty. Connect it, pair a device from the Devices tab, then paste the one-time token into the MN4 add-on — the token is shown once and only its hash is kept. The store lives at data/user/marginnote4/<name>.db and is deleted with the library; nothing in MarginNote itself is touched.
• MarginNote libraries are not swept by rag. Like an Obsidian vault, they are reached only through their own tools, so Book and rag_search skip them instead of reporting an empty result.
• The new image-description knobs apply to the next index build, not the next question, and live under Settings → Knowledge Base.

Full Changelog: v1.5.15...v1.5.16

DeepTutor v1.5.15 Release Notes

Release Date: 2026.08.20

v1.5.14 put the document next to the conversation. This one is mostly about what sits behind it: PageIndex becomes something you can host yourself and retrieves by reasoning over a document tree, the question bank stops being a list you cannot file into, and third-party packages can now register their own tools and capabilities. Nearly all of it arrived as community pull requests. Drop-in — no migrations, nothing to re-index.

What's New

PageIndex you can host yourself, and retrieval that reasons

PageIndex OSS joins the engine list as its own knowledge-base type: the same interface as the hosted service, bound to the base's local library, driven by the LLM you already configured instead of a PageIndex API key.

Retrieval changed underneath both variants. A PageIndex base used to be read through a built-in MCP server; that path is gone, replaced by a small reading loop that walks the document tree — structure first, then only the pages it needs. Fewer moving parts, and the same page-level citations come back.

The question bank stops being write-only

addEntryToCategory shipped in v1.3.6 and was never called from the frontend, so for eleven releases a learner could create categories and never put anything in them. The quiz card's bespoke dropdown now uses the shared category menu that does call it.

The page is rebuilt around the three things a flat list could not do — search, batch selection, and an inbox for questions nobody has filed yet. Graded Mastery Path questions carry their explanation and difficulty in with them.

And the tutor can finally file for you. Asking it to group your wrong answers had no writable handle on the bank, so it reached for write_note and your request quietly became a notebook record — the Chinese write_note hint even listed 错题分析 as a reason to append. The new question_bank tool is name-addressed: organize takes a category name and creates it if missing, so filing is one call after one listing. It mounts only when the bank has entries.

Third-party tools and capabilities

Two entry-point groups let an installed package extend DeepTutor without touching the tree. deeptutor.plugins was already imported by the capability registry and /plugins/list behind a try/except — but the module never existed, so plugin discovery was a dead path; it is now real. deeptutor.loop_capabilities registers chat-loop capabilities alongside the built-ins, which win on name collisions. Broken entry points are skipped rather than fatal, and discovery is cached per process so plugin capabilities stay singletons.

Apache Tika parsing

A seventh document-parsing engine, selectable in Settings → Knowledge Base. Tika is remote-only: no Python package, no model download — it points at an Apache Tika server (TIKA_SERVER_URL) and converts a broad set of formats to Markdown.

LightRAG's indexing knobs, in the UI

max_concurrent_files, llm_model_max_async, and entity_extract_max_gleaning reached runtime settings and the API in #877 but had no inputs, so they were reachable only by hand-editing config. They now sit under their own Indexing divider — a different axis from the query knobs above, because they shape how a base is built, so a change applies to the next build rather than the next question. The wiring asks the installed RAG-Anything what it accepts and drops the rest with a warning, so an older install keeps running on library defaults instead of raising.

Rebuilding a document tree in a knowledge base

Three fixes finally close #866. A linked folder's subdirectories stopped collapsing into raw/'s top level; same-named documents from different subtrees stopped silently dropping one another (a clash between different bytes stages under a free sibling name, identical bytes still dedup); and uploads now take an optional destination folder.

That last one was the actual blocker. A browser folder pick reports each file's path relative to the directory you chose, so adding 应用开发/钉钉CLI/ one subtree at a time arrived as 钉钉CLI/... with no way to say where it belonged — every batch piled up at the root, and the missing ancestor was never in the payload to begin with. The picker now offers the base's existing folders once files are staged.

Book: a learning-capture inbox

Reading segments you select are kept per book with an explicit status lifecycle, so captures can be reviewed before they go anywhere. Separately, drift warnings got honest: stale-page detection is scoped to the KB documents that actually changed, and a warning will not clear while flagged pages are still awaiting recompilation.

Whisper — a community contribution

/whisper is a two-seat counselling-practice room contributed by @alanguan73: the tutor plays the visitor, you take the trainee seat, and a supervisor whispers coaching only the trainee sees, with an end-of-session debrief. It lives under Learning Space → More Projects and needs its own capability package installed — the surface ships, the counselling capability is not part of DeepTutor.

The generally useful half of that work is in the runtime: a capability can now publish a body and its own declared extras on CAPABILITY_COMPLETE, while capability, session_id, and turn_id stay unspoofable. Only the explicitly declared sub-dict goes on the event bus — turn metadata is a scratchpad holding live callables and your ask_user answers, and it was never a wire format.

Assorted

• The model knows what day it is. Without the real date it resolved "today" from its training cutoff when composing web searches. The injected block is day-granular, so the system prompt stays byte-stable within a day and keeps prompt-cache hits.
• Deleting a turn no longer blanks the session. Descendants pointed at deleted rows, the session lost its root, and the page rendered empty (#912). Deleted rows are spliced out of the parent-pointer tree, and already-corrupted sessions are recovered from their oldest orphan.
• A stale CA bundle no longer breaks every LLM call. A leftover SSL_CERT_FILE / SSL_CERT_DIR — common after cloning a conda env without ca-certificates — made httpx raise mid-construction; broken paths are dropped so TLS falls back to the default bundle.
• Thinking tags are filtered on non-SSE local streams too. That branch passed reasoning blocks straight through; both branches now share one incremental parser, so a tag split across chunks or left unclosed behaves the same either way.
• Unhandled server errors return JSON instead of Starlette's plain-text 500, and the handler stays inside the middleware stack so the response still carries CORS headers.
• Obsidian vaults survive real-world files — undecodable bytes and date-typed frontmatter are tolerated, and a vault that fails to open says why instead of failing opaquely.
• A stuck session load ends in a retryable state rather than spinning, and token usage emitted as plain dicts by native adapters is recorded instead of lost.
• Mastery reads stop inventing paths, end_loop is honored after an ask_user resume, and the codebuddy extra resolves again.
• The frontend is linted in CI. ESLint now runs on web/ on every build.

The docs at deeptutor.info were refreshed alongside this release.

Upgrade Notes

pip install -U deeptutor; Docker users pull ghcr.io/hkuds/deeptutor:latest. No schema changes, no re-index, no migration.

• PageIndex OSS needs an API-key or local LLM profile. An OAuth-only provider (OpenAI Codex, GitHub Copilot, CodeBuddy) cannot drive indexing and is rejected with an explanation. OSS bases are PDF-only, and at most one may be selected per request.
• PageIndex's built-in MCP server is gone. Nothing to configure — hosted bases keep working through the new reading loop. If you had pinned that MCP server anywhere yourself, drop it.
• Tika installs nothing. Run an Apache Tika server and point TIKA_SERVER_URL at it (default http://localhost:9998); there is no parse-tika extra because there is no Python package.
• The LightRAG extra's floor moved to raganything>=1.2.5, the first release carrying the keyword passthrough. Older installs are not broken — unsupported knobs are dropped with a warning — but the three new ones need that floor to take effect. The knobs apply to the next build, not the next question.
• Book drift warnings re-baseline once. Fingerprints now carry a scheme tag, so changing the formula re-baselines existing books instead of marking every one of them stale.
• Whisper is not a primary nav entry. It sits under Learning Space → More Projects, and the room needs its own capability package — a stock install has the page but not the counselling capability behind it.

Full Changelog: v1.5.14...v1.5.15

DeepTutor v1.5.14 Release Notes

Release Date: 2026.08.19

v1.5.13 made a book something you read. This one puts the assistant next to what you are reading: a document opens beside the thread, and every claim comes back with the page it came from. Three other shifts sit around it — DeepTutor can configure itself from a chat turn, a Tencent IMA library becomes something you browse and write to rather than only search, and notebooks get a console of their own. Drop-in — no migrations, nothing to re-index.

What's New

Immersive Reading — the document open beside the thread

Pick Immersive Reading in the capability menu and open a PDF, a slide deck, or any document the knowledge base already accepts. The reader takes about two thirds of the workspace, the conversation keeps the rest, and the seam between them drags.

The assistant reads the same units you see — PDF pages, slides, or roughly page-sized sections for formats that have no pages of their own — so an answer cites [p.12] and the reader scrolls there and highlights the sentence behind the claim. Select a passage and ask about it, highlight as you go and attach notes, then take your marks with you: export a real annotated PDF that opens with the highlights intact in Preview or Acrobat, or Markdown to paste into your own notes.

Two decisions make it grounded rather than merely confident. A reading turn keeps the whole chat surface — web search, code execution, your other knowledge bases — because the five reading tools are added to it, never substituted for it. And before the model runs at all, DeepTutor runs your own question against the open document and hands it the top hits, so grounding happens even with models that would never have called a read tool on their own. It is a plain search, not a second LLM pass: no extra tokens, no latency before the first word.

Ask DeepTutor to configure itself

"Switch the interface to Chinese and use a better PDF parser" is now something you say rather than something you go and click. A turn can inspect the install, apply a setting, install a parsing engine or fetch its model weights — following the log live inside the single call instead of polling for it — and ask you for a credential.

Three rules keep that from being reckless. A new model or provider is probed before it is committed, against a candidate configuration that never reaches disk, so the assistant cannot switch itself onto something unreachable and cut off its own power supply mid-conversation. API keys never enter the model's context: it opens the matching form and your browser posts the key straight to the server. And every knob it can touch is one row in a single table carrying its own scope and effect, so you are told whether a change is instant, needs a restart, or invalidates your embeddings — instead of finding out later.

Tencent IMA: a library you browse and write to

An IMA library was searchable and nothing else. It now also answers "what is actually in here" — the knowledge-base file list reads the library's own browse API instead of reporting a connected base as non-enumerable, and a listing cut short by its request budget is labelled a lower bound rather than passed off as a total.

From a chat turn you can list the library, read a whole source rather than the retrieved fragments, search your notes by recency, add URLs for IMA to ingest, and write a note back. These tools are additive: rag still serves an IMA library, because it is genuinely searchable over HTTP, and attaching one no longer costs you web search or your other bases.

Connected knowledge bases are searchable again

v1.5.13 stopped Book from sweeping connected knowledge bases: the sweep returned nothing, and "nothing" was indistinguishable from a source with no relevant content. That fix was drawn too wide. Only an Obsidian vault (no index at all) and a connected subagent (not a document collection) are genuinely unreachable — a linked folder mounts an index built elsewhere, and LightRAG Server and IMA offload retrieval over HTTP. All three were being set aside, so every book quietly dropped them. Retrieval now asks whether a base can be retrieved from, not whether it is connected.

Notebooks get a console

Notebooks moved out of the Space document layout into their own full-height console at /notebook (the old link redirects, deep links included). Records can be copied or moved between notebooks, and a whole notebook exports as one Markdown document.

Three defects went with it. Concurrent saves could clobber one another; each notebook now has its own lock and every write is atomic, so a crash leaves the previous file rather than a truncated one. A notebook whose file is damaged is surfaced as a flagged row instead of vanishing from the list. And renaming a record used to clear its knowledge-base link, because the API forwarded every field whether or not you sent it.

Settings writes stop overwriting each other

Two writers shared interface.json and neither's lock covered the other. Measured before the fix, six preference saves racing six writes from a chat turn lost every one of the saves. Both now go through one lock and one atomic replace. Separately, the settings endpoints stopped writing back the defaults-merged view of your settings: changing your theme used to freeze that day's defaults into your file as explicit choices, so you silently stopped following later changes to any of them.

Assorted

• The capability menu was regrouped. Chat, Quiz, Visualize, Mastery Path, and Immersive Reading are one click away; Research and Solve moved under More Capabilities. The grouping is now purely about menu order — it used to key off which engine a capability ran on, which meant the menu could not be reordered without lying about the engine.
• write_note reports a failure it used to hide. A record id came back even when no notebook accepted the write, and that was read as success.
• A damaged notebook no longer takes a chat turn down while resolving notebook references, and /notebook/health is reachable again — it was declared after /{notebook_id} and had been shadowed by it.

Upgrade Notes

pip install -U deeptutor; Docker users pull ghcr.io/hkuds/deeptutor:latest. No schema changes, no re-index, no migration.

• Immersive Reading stores materials per user under a new reading workspace directory, created on first use. Nothing is written until you open a document.
• The capability picker looks different. Research and Solve are now under More Capabilities; nothing was removed, and a session that was using either keeps working.
• Reading needs no new Python dependency (PyMuPDF is already core), and the PDF viewer ships with the frontend bundle — source installs pick it up on the next npm install.
• A scanned, image-only document is rejected with an explanation rather than opening as an empty reader. Run it through OCR first, or index it in a knowledge base with a parsing engine that does OCR.

Full Changelog: v1.5.13...v1.5.14

DeepTutor v1.5.13 Release Notes

Release Date: 2026.08.17

v1.5.12 was about where an answer's material comes from. This one is mostly about Book — the surface that turns that material into something you read rather than something you chat with. A book could be generated but not really used: the page froze while it was being written, the progress it claimed to track was never written down, and what you got could not leave the app. That gap is the bulk of this release. The home screen also stops asking you to start from a blank composer. Drop-in — no migrations, nothing to re-index.

What's New

Watch a book being written, then finish it and take it with you

Compilation outlives the request that started it: confirm_spine returns as soon as the page shells exist, while the work it queued runs for minutes. The event bus was owned by that request and closed with it, so every subsequent event was dropped and "watch your book being written" degraded into a frozen page. The stream is now owned per book by the process, so it survives the request, a refresh, and a reconnect.

Reading progress is now actually recorded. visited_page_ids and bookmarked_page_ids had been declared but never written for the life of the feature; visited pages, bookmarks, and quiz attempts now roll up into a completion score and a list of weak chapters.

And a book can leave the app: export to a self-contained Markdown document. Every block type gets a text projection, and inherently visual blocks (a rendered animation, an interactive widget) degrade to their description plus a pointer instead of vanishing silently. Non-ASCII titles survive the download — a Chinese or accented book name used to fail the request outright.

Know what a book costs before you approve it — and don't pay twice

Confirming a spine kicks off dozens of LLM calls and many minutes of work. The editor now shows a live per-chapter estimate derived from the Section Architect's own templates, so the number cannot drift from what actually gets generated, and it stays accurate while you add, remove, or retype chapters.

Two scheduling defects that were invisible in production are fixed: the same page could be compiled twice concurrently — billed twice, one result silently discarded — and a book would grind on through a provider outage until every chapter was half-generated. The source sweep is bounded too. Ungated, eight knowledge bases against a dozen queries fired roughly a hundred concurrent provider calls; the cap is now allocated round-robin, so it isn't spent entirely on the first few bases.

Connected knowledge bases stop silently contributing nothing

A connected KB — an Obsidian vault, a remote LightRAG or IMA library, a subagent CLI — has no local index, so rag_search returns nothing for it. Book generation swept them anyway, and the empty result was indistinguishable from a source with no relevant content: attach your vault, and nothing ever told you it contributed zero. Retrieval now tells indexed bases and connected pointers apart and routes each accordingly.

Three places to start, drawn from what you were actually doing

The home composer now offers three starter suggestions built from your memory — the L3 synthesis plus your last several activities across surfaces. They propose a specific thing to understand rather than a way to revisit history, and they're sized per language so they don't overflow. A new recall memory read backs them, and snapshot stamps are read without loading entity content.

Mastery paths follow the conversation

A path outlives any one chat, and a chat may work several paths in sequence. Moving a live turn between paths now happens in one place — lease, session preference, and live turn changed together, release before acquire — so a rejected handoff leaves the learner where they were instead of half-moved. Path state and turn recovery are hardened, teaching content stays visible, qualitative reviews are scheduled, and deleting a session cleans up its path.

Tencent IMA credentials move up to the account

IMA credentials used to live only on each KB. They now also resolve at the account level from Knowledge → the IMA engine page, the way PageIndex's key does, with the per-KB pair still winning when it is complete. Existing bindings keep working untouched, and rotating the account key updates every KB that relies on it. Read-only IMA connections and source-text retrieval are fixed alongside.

Assorted

• EPUB is a supported knowledge-base format, and Docling can parse remotely against a Docling Serve server (mode=remote) with no local install or model downloads.
• Generated code is parsed before it reaches you. A truncated snippet used to ship with nothing marking it unchecked.
• The Overview chapter stays singular. Re-confirming a spine grew a second one each time, and the page was rebuilt wholesale — the one path that bypassed edited_by_user protection. Its wording is also no longer hard-coded to Chinese-or-English while the picker offers eleven languages.
• Quiz blocks read the question pipeline directly instead of a legacy facade that discarded progress from the slowest block.
• Knowledge: large uploads stream through the web layer, document parsing runs off the event loop, docstore probes are cached and deduped in kb list, and GraphRAG model/embedding compatibility is hardened.
• Partners: data is isolated per user, an invalid channel config no longer takes the others down, the tool list follows the global chat toggles, and a partner reconnects after its tab goes inactive.
• Models & providers: the model catalog and provider transport recover instead of staying broken, catalog secrets are protected in the settings API, GPT-5 agentic tools use the Responses API, provider stream-failure boundaries survive, and completed turn message IDs persist across reconnects.
• Runtime: the active virtualenv is visible inside the bwrap sandbox, invalid homes and placeholder OpenAI keys are rejected, Windows .cmd shims resolve before a CLI is spawned, console exception tracebacks are preserved, and mcp installs by default so the PageIndex MCP server connects.

Upgrade Notes

pip install -U deeptutor; Docker users pull ghcr.io/hkuds/deeptutor:latest. No schema changes, no re-index, no migration.

• Books compiled before this release have no recorded progress. Completion scores and weak chapters start accumulating from your next read; nothing is backfilled and no existing page is rewritten.
• A book that was mid-compile when you upgrade should be resumed, not left. The event stream is now owned per book, so reopening it reattaches to the live compile rather than showing a frozen page.
• settings/ima.json is new and optional. Existing per-KB IMA credentials keep working exactly as before — the account-level pair only fills in for KBs that don't carry their own.

Full Changelog: v1.5.12...v1.5.13

DeepTutor v1.5.12 Release Notes

Release Date: 2026.08.13

v1.5.11 was about what happens while an answer is being written. This one is about where its material comes from. The web-search layer was rebuilt onto a single table — which is how three defects that had been quietly costing you results got found — and six providers were added on top of it, most of them reachable from mainland China. A sixth document-parsing engine lands, and an MCP server whose credential you rotated now reconnects instead of answering with the one explanation that rules out the real cause. Drop-in — no migrations, nothing to re-index.

What's New

Web search rebuilt, with six new providers

The provider list had been copied into seven places — the backend registry, runtime config, the settings router, the CLI wizard, the frontend catalog, i18n, and the tests — and they had drifted apart; the frontend marked Serper deprecated while the backend still offered it. All seven now derive from one SEARCH_PROVIDERS spec table. Consolidating it surfaced three silent defects: Serper's num never reached the API, so max_results did nothing; Serper dropped its proxy configuration; and Jina had no result-count limit at all.

Six providers join on that table — Doubao, Bocha, Zhipu, Firecrawl, Baidu Qianfan, and Aliyun IQS. They appear in Settings → Catalog → Search with their credential fields derived from the spec, and deeptutor init offers them too. Doubao returns an answer rather than only links; Firecrawl adds full-page extraction. Baidu returns as qianfan on the official Qianfan API — the old baidu key stays deprecated rather than revived.

A search failure no longer fails the turn

A rate limit, timeout, or unreachable host used to end the whole turn. The request now walks your other credentialed search profiles and finally DuckDuckGo, recording what it tried under a top-level search_fallback key so the trace shows the downgrade instead of hiding it. The proxy travels with the request, so a fallback still works from behind one.

A missing API key is treated as the opposite kind of problem and still fails immediately for the six new providers. Five of them are China-hosted, and DuckDuckGo is unreachable on those networks — silently downgrading would turn "you did not configure a key" into an unexplained timeout somewhere else.

LiteParse joins the parsing engines

A sixth document-parsing engine, selectable in Settings → Knowledge Base alongside Text-only, MinerU, Docling, markitdown, and PyMuPDF4LLM. Lightweight, with no local model downloads. Install with pip install deeptutor[parse-liteparse].

MCP servers reconnect when a credential changes

Rotating a stored credential left the live connection untouched: the stored config still held a ${secret:...} reference, so its fingerprint was byte-identical and the reload diff concluded nothing had changed. Connections are now fingerprinted against the resolved config, so the account reconnects with the key it just set. Separately, a transport failure during a tool call — most often auth — was raised inside the SDK's own task group and left the caller waiting for the full tool timeout, reporting the one cause that had been ruled out. The connection is now watched during the call, so the real error is what the model and the user are told, in the second it took. URLs are redacted from those messages, since a server can carry its credential in a query parameter.

CodeBuddy and OrcaRouter

Two more model providers: CodeBuddy/WorkBuddy, which validates CodeBuddy SDK auth and starts a browser sign-in when needed, and OrcaRouter, a named OpenAI-compatible gateway available for both chat and embeddings.

Codex keeps its reasoning effort, and can see

A managed reasoning-effort override now persists instead of resetting between sessions, and OpenAI Codex is marked vision-capable, so images reach it rather than being dropped. Gemini 3 and 2.5 Pro, which reject reasoning_effort="none", now default to minimal — the lowest level those families accept.

Assorted

• RAG citations read the structured payload. Citation extraction prefers ToolResult.metadata["sources"] over parsing the textual answer, which usually yielded no sources at all; parsing remains the fallback for older traces.
• Responses tool calls no longer cross-dispatch. A missing output-item id was filled with a literal fc_0 and registered as an identity, so the next call that omitted its id resolved to the previous call's buffer and ran under its name and arguments. The placeholder is no longer an alias.
• Mastery paths are independent of chat sessions, so opening a path no longer disturbs the session you were in.
• Chat history settles at the bottom after loading, instead of landing mid-scroll.
• Assistant output renders **bold** correctly when the model emits stray spacing inside the markers.
• The obsolete Typer extra is gone from both packaging manifests.

Upgrade Notes

pip install -U deeptutor; Docker users pull ghcr.io/hkuds/deeptutor:latest. No schema changes, no re-index, no migration.

• GET /api/v1/settings/provider-choices changed shape. Each entry in the search array gained requires_api_key, requires_base_url, soft_fallback, and status, and the array now also returns exa, baidu, and openrouter with status: "deprecated" — deliberately, so a client can tell a stale configuration from a misspelled name. DeepTutor's own UI filters on status; any other consumer that renders the array directly will show three deprecated options until it does the same.
• get_providers_info() entries gained requires_base_url, which reaches deeptutor config show and the /api/v1/system diagnostics.
• An unrecognized search provider name now falls back to DuckDuckGo rather than raising. Previously only exa, baidu, and openrouter were downgraded and any other unknown name raised. An explicit none still raises, because that means search is switched off.
• get_available_providers() returns more than it used to. It previously instantiated each provider and swallowed the credential error, so it effectively reported only the active provider plus the two that need no key; it now reports every profile whose credentials are complete.
• Brave is labelled Brave, not Brave Search, in CLI diagnostics — the UI already showed the shorter name.

Full Changelog: v1.5.11...v1.5.12

DeepTutor v1.5.11 Release Notes

Release Date: 2026.08.10

v1.5.10 was about the paths underneath a request holding up; this one is about what happens while the answer is still being written. Prose that shared a round with a tool call used to vanish into the trace, a truncated generation was read as the model deciding it had finished, and local indexing sat on the event loop everything else needed. The settings strip also stops restating what the Models page already tells you and starts showing the one number nothing else did: what DeepTutor is actually costing in memory. Drop-in — no migrations, nothing to re-index.

What's New

Text around a tool call is no longer lost

DeepSeek's Anthropic-compatible endpoint interleaves user-facing prose and DSML tool-call markup in a single content stream. The old handling was all-or-nothing: once a round's content channel showed DSML markup, the rest of that round was diverted to the thinking channel, so any explanation the model wrote around its call disappeared from the answer. A streaming filter now removes only the DSML envelope and the invoke blocks, incrementally — text before, between, and after a call streams and persists as part of the reply. An incomplete call is released verbatim on flush rather than swallowed, and a 512-character ceiling means a stray < in ordinary prose cannot make the live stream wait forever for a closing bracket.

DSML array and object arguments decode correctly

DeepSeek marks essentially every DSML parameter string="true", JSON arrays and objects included, so a container argument arrived at the tool as a string of JSON. Parameter decoding now consults the declared tool schema: a parameter the schema types as array or object is parsed when the payload actually matches, and the provider's string contract still wins everywhere else. The schema catalog is kept even when a provider rejects native tools and the loop falls back to DSML, which is exactly when the parser needs it.

A truncated generation asks for a continuation

A length finish is an incomplete generation, not the model choosing to stop — but it was treated as a finish, so the reply ended mid-sentence. The loop now keeps the visible prefix and asks for a continuation, and the assembled answer carries the prefix through to persistence and the SDK. The round budget was restructured to make this safe: exploration rounds, then a small bounded settlement window, then a single tool-less hard finish, so repeated truncation and malformed tool cycles share one absolute upper bound of exploration + 4.

Live memory usage in Settings

The settings status strip carried Backend, LLM, Embedding, and Search — three of which restated what the Models and Chat pages already own. It now carries the two runtime facts no settings page shows: whether the backend is up, and resident memory across the whole DeepTutor process tree — backend, the Next.js server, and whatever sandboxes and subagent CLIs are alive — with a per-process split inline and a pressure dot that turns amber past two thirds of the limit. It is served by a new GET /api/v1/system/memory; psutil reads the tree and is imported lazily with a /proc fallback, so a missing wheel costs the strip and not the app. Non-admins and platforms where the tree cannot be read get {available: false} and no strip.

Local LightRAG indexing stops stalling everything else

RAG-Anything's local storage backends do synchronous graph merging and JSON serialization from inside async methods, so indexing a document on the service event loop froze unrelated API and LLM work for its duration. Indexing now runs on a worker thread's own event loop, with a narrow bridge that forwards LLM, vision, and embedding calls back to the request's loop, carrying a copy of the caller's context so request-local model and user configuration stays visible. Remote LightRAG servers are unaffected.

Mastery works from the persisted question, not the model's retelling

A posed question now projects into a small public contract — prompt, type, and the option label/body map — shared by registration, presentation, and grading, with the expected answer staying server-side. ask_user renders that persisted state instead of display data the model re-authored, so the choices a learner sees are the choices that will be graded. Registration validates the quiz shape rather than silently accepting a contradictory one: a missing type is inferred from the payload, short/open questions reject options, and a choice question must carry real option bodies instead of bare A/B/C labels.

Assorted

• Connected knowledge bases answer honestly about local files. A linked external resource has no DeepTutor-managed raw/ directory; listing its files returns an empty collection instead of inventing one, and endpoints that require a local file return an explicit 409.
• Generated output artifacts are served request-scoped. A new /api/outputs endpoint resolves and authorizes a path in one operation and fails closed with a 404 when there is no request user, so an auth-context regression cannot hand an administrator's artifact to an ordinary request.
• Visualize iframes shrink as well as grow — the height bridge measures body content instead of a root height the host had already stretched, and coalesces reports into one animation frame.
• The chat page's model list is fetched once. Option loading moved into a hook with single-flight de-duplication, so concurrent mounts and a tab-focus refresh no longer stack up identical requests.

Upgrade Notes

pip install -U deeptutor; Docker users pull ghcr.io/hkuds/deeptutor:latest. No schema changes, no re-index, no migration.

• psutil is a new dependency and installs with the upgrade. It is imported lazily behind a /proc fallback — if your environment cannot provide it, the memory strip stays hidden and nothing else changes.

Full Changelog: v1.5.10...v1.5.11

DeepTutor v1.5.10 Release Notes

Release Date: 2026.08.07

v1.5.9 was about providers; this one is about the paths underneath them holding up — a batch upload that stalled every other request, a knowledge-base list that rescanned every index, a tool call dispatched with no arguments and retried until the budget ran out. Two things that were quietly missing also land: an account can sign in to its own Codex, and the model's reply language is finally its own setting. Drop-in — no migrations, nothing to re-index.

What's New

Every account can sign in to its own Codex

A Codex token authorizes one person's ChatGPT plan, so the profile was correctly never grantable — but the OAuth endpoints were admin-only too, which left ordinary users with no route to Codex at all. They can now sign in for themselves: the card sits under Models → LLM, and the profile it creates is written to that user's own catalog (data/users/<uid>/settings/model_catalog.json), never the shared admin one. Grants resolve personal rows alongside assigned ones in a single place, so the option list, the capability gate, and selection validation cannot disagree — and an administrator inspecting someone's grants still sees only what they assigned. Partners are refused: a partner is a synthetic user, and admitting one would mean acting on its owner's login.

Model output language is its own setting

Settings → Appearance now carries two independent toggles. Interface language covers navigation, settings, and status text; Model output language sets the default language of chat and capability replies, which until now you could only steer from the prompt. An interface.json written before the split inherits its single language into both fields, so nothing changes until you pick. The pre-session bootstrap that reads these is also public now — /login and /register stayed English before, because the anonymous read hit the gated router and 401'd; it returns theme and language only, and a choice made in this browser still wins.

A tool call with no arguments is rejected, not run

Under a large tool surface and long history, providers intermittently emit a native function call with empty arguments even where the schema marks fields required. The call was dispatched anyway, so the tool did the rejecting — exec raised "requires a non-empty command", write_note answered "Unknown mode ''" — and neither reads as "an argument is missing", so the model re-emitted the same malformed call until the loop budget ran out. A guard in front of dispatch now names the missing arguments and their accepted values (enums included), turning that into one self-correcting round. The rules stay narrow: a parameter with a default is not required, empty collections are left alone, server-injected kwargs count as supplied.

Uploads and knowledge-base listing stop holding the loop

Batch-uploading files stalled every other request — chat WebSockets included — for the whole duration of the batch: the chunked write, zip extraction, and per-file PocketBase upload all ran inline in an async context, and the follow-up staging pass sat in an async def background task, which Starlette awaits on the loop rather than in its threadpool. Both now run in a worker thread. Separately, building one KB list response reloaded configuration and rescanned every index per item; it now reuses one reconciled snapshot — a 58-KB read-only listing finishes in ~2s instead of timing out the proxy.

Deep Research reads a connected Obsidian vault directly

When the selected knowledge base is a linked Obsidian vault, the research loop no longer auto-mounts rag against an index that does not exist. It mounts the three read-only vault tools instead — obsidian_search / obsidian_read / obsidian_list — injects the vault path server-side (overwriting any model-supplied value), treats their results as citable so evidence reaches the citation manager and the final report, and swaps in an Obsidian-specific system note. Indexed KBs and no-KB runs are untouched.

The server-side backend address is IPv4 loopback everywhere

localhost resolves to ::1 first on a dual-stack host while uvicorn binds 0.0.0.0 — IPv4 only — so every rewritten /api/* request failed to connect. The launcher was fixed first; the Docker entrypoint's render_environment and web/proxy.ts's last-resort default kept the hostname and have now been brought back in sync.

Assorted

• Escape stops a streaming Partner reply, and only that: the listener bails while any dialog-role overlay is mounted, so dismissing a modal or picker no longer kills the answer behind it.
• Vision capability overrides now match claude- by vendor prefix (nothing ever began with claude-4, so that key matched nothing), and recognize Kimi K3 and Qwen3.8-Max.
• Codex context-window metadata survives the catalog round-trip instead of being dropped.
• Editing a message no longer races the refresh that follows it, so the optimistic bubble stops flickering back.
• The deeptutor-cli wheel ships the agents' prompt YAML again — it had none, so prompt loading failed and the empty result was cached for the life of the process. Misses are no longer cached either, so a resource that appears after startup is picked up on retry.

Upgrade Notes

pip install -U deeptutor; Docker users pull ghcr.io/hkuds/deeptutor:latest. No schema changes, no re-index, no migration.

• Model output language defaults to your existing interface language. The split is inherited, not reset — set it explicitly under Settings → Appearance if you want replies in a different language than the UI.
• Non-admin Codex sign-in is on by default. Each account's profile stays in its own catalog and is invisible to the administrator and to every other user; nothing an ordinary user signs into can appear in the shared model list or the grant editor.

Full Changelog: v1.5.9...v1.5.10

DeepTutor v1.5.9 Release Notes

Release Date: 2026.08.04

Where v1.5.8 was about memory, this one is about providers — Gemini's native Embedding 2 endpoint, a per-model reasoning-effort control, a Novita AI gateway — and about the paths that were quietly wrong underneath them: queries embedded as if they were documents, none turning thinking on, a capability crash arriving as a blank message. Drop-in for most installs, but docker-compose.ghcr.yml users have a one-time data migration to run before their next up.

What's New

Gemini Embedding 2 over the native API

A Gemini embedding profile now defaults to Google's native …/models/<model>:batchEmbedContents endpoint with gemini-embedding-2, authenticated with x-goog-api-key, and the endpoint follows the model you pick — including through a gateway prefix. Existing gemini-embedding-001 profiles deliberately stay on the OpenAI-compatible path: the native route sends a taskType and L2-normalizes what comes back, so moving them would change their document vectors and silently invalidate the index built from them. Point base_url at the native URL yourself to opt any model in.

Queries stop being embedded as documents

Retrieval embeddings now carry their role. LlamaIndex tags queries search_query and passages search_document, LightRAG maps its own context hint the same way, and adapters opt in explicitly (SUPPORTS_INPUT_TYPE) so a backend that never sent a role keeps not sending one. Only Cohere — which requires the field and already defaulted to search_document — changes today: document vectors are untouched, queries finally get the right role. No re-index.

A reasoning-effort selector per model

Each LLM model in the catalog gets an optional default reasoning depth next to its context window, offered only where the provider actually supports one and labelled in that provider's own vocabulary (minimal/low/medium/high/xhigh for OpenAI-style families, adaptive where that is the only on-mode, a plain on/off for the rest). Provider default (Auto) leaves the choice to the provider. Two Anthropic bugs fell out of wiring it up: none was turning thinking on with a 4096-token budget, and a stored adaptive sent to an older family drew a 400 instead of the default budget.

Novita AI, and MiniMax on the right platform

Novita AI joins the LLM gateways (novita, https://api.novita.ai/openai). MiniMax runs two separate platforms whose keys are not interchangeable, and the default now points at the global one (api.minimax.io) instead of the mainland-China one; minimax-m3 and minimax-m2.7 context windows are recorded, and detection also reads a context_size field.

Compose deployments keep all of data/

docker-compose.ghcr.yml bind-mounted only data/user, data/memory and data/knowledge_bases, so data/system (the JWT signing secret, accounts, grants, per-owner Codex tokens), data/users, data/partners and data/cli-apps lived in the container's writable layer and were discarded on every recreate. It now mounts the whole tree, matching the other Compose files. Named-volume and source-build deployments were never affected.

Codex sign-in inside a local container

Default local Docker and Podman deployments put the browser and the server on separate loopback networks, so the OAuth callback never arrived. There is now a temporary compose.codex-oauth.yaml overlay (and the equivalent docker/podman commands) that publishes ports 1455/1457 only while you sign in — with teardown, so those ports go back to your other Codex clients. See CONTAINERIZATION.md.

Failures that used to arrive as nothing

A capability that raised — or a request for one that does not exist — ended the stream without a verdict, and the turn was persisted as completed with an empty answer. The error is now marked terminal and carried through a DONE event, so the turn is stored as failed with its message and the UI shows what went wrong instead of an empty bubble.

Assorted

• The interface language you saved is honored on first load. It lived in the backend's ui settings, which only the Settings route ever read, so every other page started in English until you re-picked it in that browser. A local choice still wins.
• Visualize no longer aborts when the analysis model invents a render_type or visual_genre outside the enum — the off-enum value is dropped and the field falls back to its default.
• Credential-like query parameters (key, api_key, token, access_token) are redacted in every endpoint the wizard, the client, and error messages print.

Upgrade Notes

pip install -U deeptutor; Docker users pull ghcr.io/hkuds/deeptutor:latest. No schema changes, and nothing to re-index.

• docker-compose.ghcr.yml users: copy your state out before the next up -d. The new whole-tree mount means empty host directories would shadow what is in the container's writable layer, regenerating the auth secret (logging everyone out) and starting with no non-admin accounts. The one docker cp loop is in CONTAINERIZATION.md → One-time migration.
• MiniMax on the mainland-China platform: the default base URL is now the global endpoint. Set base_url to https://api.minimaxi.com/v1 (or https://api.minimaxi.com/anthropic) and use a China-platform key — keys are issued per platform. Saved profiles keep whatever URL they already have.
• Gemini embeddings: existing gemini-embedding-001 profiles are left where they are on purpose. New profiles and gemini-embedding-2 use the native endpoint.

Full Changelog: v1.5.8...v1.5.9

DeepTutor v1.5.8 Release Notes

Release Date: 2026.08.02

A maintenance release with one target: memory that stays put instead of climbing. A v1.5.7 source deployment grew past 14 GB before V8 gave up mid-session, and the causes turned out to be independent — a frontend dev server whose heap ceiling never reached the process holding the memory, unbounded in-process caches, and a fresh HTTP client built for every turn. Drop-in — no migrations, but a source checkout now starts differently.

What's New

The dev server was never actually capped

next dev renders in a worker it spawns itself, and V8 flags in argv are not inherited by child processes — so the long-standing node --max-old-space-size=4096 …/next dev never reached the process that holds the memory. Finding no ceiling in NODE_OPTIONS, Next substituted 50% of total RAM: a 12 GB heap on a 24 GB machine, which V8 genuinely tried to fill before dying in Ineffective mark-compacts near heap limit after 63 seconds inside a single mark-compact. web/scripts/dev.mjs now passes the ceiling through NODE_OPTIONS, which the worker does inherit and Next honors — clamped to 4 GB, and sized against the cgroup limit inside a container rather than the host's RAM.

Source installs serve a production build

deeptutor start from a checkout now builds the frontend once into .next-deeptutor and serves the standalone output, reusing that build until an input actually changes (a fingerprint over the web/ tree, the version file, and the build-time public settings). Hot reload moves to deeptutor start --dev, which keeps using .next — separate directories, so neither mode invalidates the other's output while it is running. A long-running deployment no longer pays for a dev compiler's caches.

Bounded LLM clients instead of one per turn

The chat, research and question pipelines each built a fresh OpenAI-compatible client — and with it a new HTTP connection pool — on every turn. Both the agentic client and the services-layer provider now come from a small event-loop-local LRU pool of 2, keyed on binding, model, credentials and base URL, closed on shutdown and retired when settings change. Only the selected backend's SDK is imported.

Caches with a ceiling

Knowledge-task log streams now cap events and bytes per task, expire an hour after a task ends, and leave a small completion tombstone so a late subscriber still learns the task finished. The completed-task table keeps 256 entries. The LlamaIndex index cache drops from 8 entries to 2 and evicts anything idle for 10 minutes. A book runtime is released once its queue drains instead of living for the process.

Reclaiming what was already freed

After a turn, a finished book job, or a completed knowledge-base task, DeepTutor collects cycles and — on Linux — calls malloc_trim so glibc hands free heap pages back instead of holding arenas that make RSS look permanently pinned. Containers and deeptutor start also set MALLOC_ARENA_MAX=2 and a lower trim threshold, both overridable by an operator who has tuned their own.

A keep-alive race that surfaced as 500s

web/proxy.ts forwards to the backend over Node's http.globalAgent, which reaps idle sockets on a 5s timer — identical to uvicorn's default. Both ends armed the same 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, that request died with ECONNRESET and reached the UI as "Failed to load sessions". Every uvicorn launch now sets --timeout-keep-alive 300, leaving the client as the only side that retires an idle connection.

Assorted

• deeptutor.agents, deeptutor.core.agentic, the provider-core package, the document extractor's parser libraries (PyMuPDF, pypdf, python-docx, openpyxl, python-pptx) and the LLM error-mapping rules all resolve on first use rather than at import time.
• python -m deeptutor.api.run_server no longer starts with --reload; export DEEPTUTOR_DEV_RELOAD=1 for it. Reload runs a supervisor plus a worker and retains file-watcher state, which is development machinery. deeptutor serve --reload is unchanged.

Upgrade Notes

Drop-in from v1.5.7: pip install -U deeptutor; Docker users pull ghcr.io/hkuds/deeptutor:latest. No schema or config changes.

• Source checkouts build before they serve. The first deeptutor start after upgrading runs npm run build and takes correspondingly longer; later launches reuse it until the source changes. Use deeptutor start --dev for the previous hot-reload loop. The new web/.next-deeptutor/ build directory is git-ignored.
• python -m deeptutor.api.run_server no longer reloads by default. Export DEEPTUTOR_DEV_RELOAD=1 to restore it.

Full Changelog: v1.5.7...v1.5.8