DeepTutor is not a collection of disconnected AI features. It is a learning runtime that packages the learner’s world once, gives one capability ownership of a turn, lets tools perform bounded actions, and streams the same typed work to every interface.
The core design separates turn ownership from action execution. Capabilities own multi-stage learning workflows; tools return bounded results to an agentic loop; deterministic engine state guards planning and mastery; StreamBus decouples execution from presentation; and a three-layer memory system turns raw activity into auditable personalization.
“Agent-native” becomes concrete only when the system says who owns the turn, what may mutate state, how uncertainty is repaired, and which data is safe to publish.
A BaseTool exposes a schema and returns ToolResult. A BaseCapability owns a named, staged run(). The orchestrator resolves exactly one capability for the turn.
Deep Solve and Mastery Path reuse AgenticChatPipeline, then add stateful plan or mastery tools. Deep Research and Visualize retain specialist pipelines where their artifact-production shape genuinely differs.
The learning loop depends on contracts at both ends. Context determines which tools and skills can mount; protocol labels constrain the model’s next action; tool results can pause or terminate; the event stream makes progress observable; memory consolidation happens outside the immediate answer path.
Each card states what must be true before the component runs, what it guarantees afterward, and the internal mechanism that transforms one into the other. Switch between algorithm and software views, then open a card to walk the transformation step by step.
Generate a session ID, resolve active_capability or "chat", reject unknown names as terminal events, then run one owner asynchronously.
Each iteration obtains a labeled step, checks protocol violations, repairs malformed outputs, dispatches tools, handles intermediate labels, or terminates.
Tool results return content, sources, UI metadata, success state, and explicit control signals. ask_user pauses the same turn and resumes with the reply.
Context flags mount RAG, source, memory, notebook, execution, and mastery tools only when relevant. Deferred tools expose compact manifests and load schemas into the live list on demand.
Deep Solve stores a committed plan and bounded replan budget. Mastery Path binds persisted paths, grades questions, and uses a hard per-type gate plus spaced review.
Append raw surface traces, consolidate readable per-surface facts, then synthesize recent/profile/scope knowledge across surfaces. Preferences remain an explicit write path.
Routes a UnifiedContext, owns the StreamBus lifecycle, normalizes errors into terminal events, and publishes a safe completion envelope.
deeptutor/runtime/orchestrator.py ↗The canonical request envelope for every tool, capability, and plugin invocation. Its metadata field is a scratchpad—not automatically public wire data.
deeptutor/core/context.py ↗Separate bounded function schemas/results from turn-owning manifests and staged run methods.
core/tool_protocol.py ↗ core/capability_protocol.py ↗Load built-ins, discover plugins, resolve names and aliases, build model-provider schemas, and expose manifests without coupling the orchestrator to each implementation.
deeptutor/runtime/registry/ ↗Composes prompt blocks, contextual tools, provider-scoped views, usage tracking, context budgets, and the capability-neutral agent loop.
agents/chat/agentic_pipeline.py ↗Owns iteration, label validation, repair, terminal handling, intermediate hooks, tool dispatch, pause/resume, forced finalization, and aggregated sources.
core/agentic/loop.py ↗Turn-scoped async fan-out with bounded optional history, late-subscriber replay, cross-loop wake-up, typed convenience helpers, and close sentinels.
core/stream_bus.py ↗A stateless facade over per-user paths, atomic Markdown writes, L2/L3 consolidation, explicit preferences, audits, and trace provenance.
services/memory/store.py ↗These excerpts are simplified from the checked-out source. They preserve the governing behavior while omitting defensive branches, trace metadata, and provider-specific plumbing.
Capabilities may opt values into a publishable sub-dictionary. Capability, session, and turn identifiers always win.
Protocol violations are classified, emitted as warnings, appended as repair messages, and retried within a bounded iteration budget.
A ToolResult can carry a structured pause payload. The host awaits the learner’s reply, substitutes it into the tool message, and continues the iteration.
ask_user no longer fakes a completed turn and starts another. The in-flight loop remains the owner, preserving its capability mode, tool results, trace, and iteration state.
MemoryStore prevents duplicate explicit preferences, writes atomically, and separates direct preference writes from automatically consolidated recent/profile/scope documents.
The repository’s strongest lessons are not “use agents” or “add memory.” They are about where to place ownership, evidence, and deterministic authority around probabilistic behavior.
Unify interfaces at the request and event contracts so new clients do not fork tutor behavior.
Keep bounded actions composable and let purpose-built workflows own control.
Convert malformed model behavior into bounded, observable feedback rather than undefined execution.
Let the model teach flexibly while the engine enforces plan and mastery invariants.
Keep prompt surfaces small with manifests, then load full tools, skills, and sources on demand.
File-backed evidence, summaries, and synthesis allow correction that hidden memory cannot.
DeepTutor’s architecture treats learning behavior as a probabilistic process inside explicit software contracts—not as a prompt that happens to call tools.
Invalidation test: this conclusion weakens if major entrypoints bypass UnifiedContext or ChatOrchestrator, if mastery progresses without engine-state evidence, or if consumers depend on capability-specific private metadata rather than the shared event contract.
Source groups are stable evidence handles for this artifact. Documentation-only claims are labeled separately from behavior verified in implementation.