Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

3.9 KB
Raw Blame

Tools and capabilities

Handbook · Architecture · Modules · Plugins

The two contracts

BaseTool, ToolDefinition, and ToolResult describe one operation selected by a model. A tool validates arguments, performs the operation and returns content plus structured metadata/error state. Availability is not equivalent to permission to access every resource.

TurnCapability and CapabilityManifest describe a pipeline that owns a turn. A capability consumes UnifiedContext and emits stream events. Capabilities converge on emit_capability_result() for the response payload and cost_summary; do not invent another completion envelope.

The built-in catalog is derived from modules/manifests/ by builtin_capabilities.py. Use deeptutor module list, deeptutor plugin list and deeptutor plugin info to inspect the current installation rather than assuming every source feature is available in a core-only wheel environment.

Mounting rules

The eight user-toggleable tools are brainstorm, web_search, paper_search, zotero_search, reason, geogebra_analysis, imagegen and videogen. USER_TOGGLEABLE_TOOL_NAMES in tools/builtin/__init__.py is the authoritative list; CLI --tool selects from it.

CONFIGURABLE_BUILTIN_TOOL_NAMES declares context-gated tools, including research, retrieval, memory, notebook, execution and deferred tool discovery. tool_composition.py owns mount flags and always-available workspace tools. Capability-owned solve, mastery and other specialized tools follow their activation contracts. The Partner allow/deny surface can further narrow access.

Account grants, workspace resource policies, module selection and capability activation must all remain effective at discovery and dispatch. A tool name in a UI or a manifest must not bypass those checks. MCP/CLI deferred discovery must use the existing loader rather than installing a parallel registry.

Add or change a built-in

  1. Implement the typed operation or capability in its owning module. Keep optional libraries out of metadata-only imports.
  2. Update the tool spec or capability declaration, aliases and the owning module manifest. The lazy tool descriptors live in builtin_specs.py.
  3. Put mounting logic in the existing composition/activation owner. Decide explicitly whether a tool is user-toggleable, context-gated or capability-owned.
  4. Update request validation and translated prompts where needed. Capability prompts live under capabilities/prompts/; some agent implementations own additional prompts in their own directory.
  5. Test metadata/implementation parity, missing-module behavior, authorized resource scope, failure and cancellation, and the public result envelope. Follow Testing for schema regeneration and broader checks.

For an independently distributed package, use the plugin contract and Learning Echo example instead of modifying built-in registration. Reading toolbar actions have a separate Reading extension protocol.

Diagnose an unexpected tool call

Compare the active module state, capability, selected resources, user tool selection and workspace policies with the actual schemas admitted to the model request. Then inspect dispatch and the returned evidence. A selected KB does not prove retrieval ran; a retrieved URL does not prove pixels reached the model. See source visuals and answer-quality diagnosis.