Skip to content

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

4.1 KB
Raw Blame

Developing DeepTutor

Handbook · Architecture · Testing

Prepare a source environment

Follow Agent setup for Python 3.11–3.14, Node.js 22 LTS, provider configuration and readiness. A source checkout exposes all modules; install its external dependencies before the editable core:

python -m pip install -r requirements/full.txt
python -m pip install -e . --no-deps
python scripts/install_extras.py dev
cd web
npm ci --legacy-peer-deps
cd ..

Use scripts/install_extras.py for optional source dependencies. Installing feature wheels over an editable checkout can obscure source ownership; use a separate environment for wheel lifecycle testing. System executables such as FFmpeg and LaTeX remain separate prerequisites for the features that need them.

Inspect git status, the active branch and remotes before updating. Develop against dev; follow contribution policy for PR targets. Reuse an appropriate task checkout or use a separate worktree when concurrent work needs isolation. Preserve unrelated edits. Keep runtime data and test outputs out of Git.

Use a dedicated runtime home

DEEPTUTOR_HOME is the directory that owns data/, not data/ itself. Pick an explicit, private development home and use it for every command. For example, in a fresh shell:

export DEEPTUTOR_HOME="$HOME/.local/share/deeptutor-dev"
deeptutor init --non-interactive
deeptutor config show
deeptutor module list

Do not point fixtures at an existing learner's runtime. A Content Workspace is a separate storage and authorization scope; see workspaces. The application does not automatically load the project's .env file.

Run and inspect

For the combined launcher, use deeptutor start and read the actual URLs in its output. For separate development processes, run the API and frontend in two terminals with the same chosen runtime home:

# Terminal 1: API, with reload
deeptutor serve --host 127.0.0.1 --port 8001 --reload
# Terminal 2: frontend, from web/
DEEPTUTOR_API_BASE_URL=http://127.0.0.1:8001 npm run dev

Choose free ports; do not stop unrelated services. Confirm browser requests reach the intended API through the frontend proxy. A listening frontend alone does not establish provider, module or turn readiness. Use deeptutor doctor --format json and the original user operation to verify.

Make a change at its owner

  1. Reproduce the behavior with a minimal synthetic fixture. Identify whether the owner is the adapter, shared runtime, capability, tool, feature store, provider, or frontend projection.
  2. Read the nearest implementation and its tests. For API changes, follow request validation through authentication, account/workspace resolution, persistence, events and UI consumption.
  3. Change that owner rather than adding a second runtime, path resolver, provider client or storage abstraction. Shared protocols stay import-light.
  4. Update module declarations, request contracts, prompts and locale strings when affected. Regenerate derived files with their owning scripts.
  5. Run checks appropriate to the change, reproduce the original action, and explain any validation limits in the PR.

Use explicit argument lists and shell=False for subprocesses; retain process tree cleanup on cancellation. Resolve storage through the existing account and workspace context rather than constructing a global data path. Never return credentials or private provider-replay metadata to browser responses.

Generated files and documentation

The repository intentionally tracks generated API contracts, requirement files and dependency locks. Update their generators or authoritative inputs, then regenerate. web/.next*, installed dependencies, bytecode, logs and manual acceptance artifacts stay untracked.

Update the relevant handbook topic and README links when a public behavior changes. Put reusable executable examples under this handbook's examples/. Keep command examples usable from the repository root and avoid personal machine paths.