# AI use cases for Deep Tutor (HKUDS/DeepTutor)

Repo: [HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) | Use cases: 3 | Page: https://dedupedai.com/use-cases/hkuds-deeptutor/

DeepTutor is an open-source, agent-native tutoring workspace for lifelong personalized learning. Chat, Quiz, Research, Visualize, Solve, Mastery Path and Reading share session context inside a workspace per subject, with knowledge bases, notebooks, a Question Bank and partners that can consult live agents such as Claude Code and Codex. It runs as a Web app and CLI from Docker, PyPI or source.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Try the full Deep Tutor web app in one Docker command: https://dedupedai.com/use-cases/hkuds-deeptutor/try-the-full-tutor-in-docker/
- Install the Deep Tutor web app and CLI with pip: https://dedupedai.com/use-cases/hkuds-deeptutor/install-deeptutor-with-pip/
- Score which retrieval setup works best on your knowledge base: https://dedupedai.com/use-cases/hkuds-deeptutor/score-your-knowledge-base-retrieval/

## How to try the full Deep Tutor web app in one Docker command with Deep Tutor

Repo: [HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) | Difficulty: Beginner | Time: 15 minutes | Basis: From the README

Run the published image, open the web app and configure a provider and model.

**Who it is for:** A learner who wants to try an AI tutor without installing Python or Node.js.

**The problem:** Setting up a multi-mode learning app usually means installing a backend, a frontend and their runtimes.

**The outcome:** The full Deep Tutor web app on port 3782 with settings kept in a named volume.

### Steps

1. Run the `docker run --rm --name deeptutor` command from the README, publishing 127.0.0.1:3782:3782 with the deeptutor-data volume and ghcr.io/hkuds/deeptutor:latest
2. Open http://127.0.0.1:3782
3. Configure a provider and model in Settings, Providers and Language models
4. Create a workspace for a subject and start in Chat

### Prompt to paste into your agent

```text
Start DeepTutor with Docker using the ghcr.io/hkuds/deeptutor:latest image on 127.0.0.1:3782 with a deeptutor-data volume, then tell me which Settings, Providers fields I need for <provider>.
```

### Caveat

Desktop installers are previews on dev only; the v1.7.0 release does not include them.

Risk, credentials: Your model provider API key is stored in the app's settings volume, so keep the port bound to 127.0.0.1 unless you protect it.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/hkuds-deeptutor/try-the-full-tutor-in-docker/

## How to install the Deep Tutor web app and CLI with pip with Deep Tutor

Repo: [HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) | Difficulty: Beginner | Time: 20 minutes | Basis: From the README

Use the PyPI package, run the setup wizard and start backend and frontend together.

**Who it is for:** A developer who wants Deep Tutor running locally with its CLI available.

**The problem:** Picking ports, a provider and optional embedding and search by hand is error prone.

**The outcome:** A local Deep Tutor install started with one command and stopped with Ctrl+C.

### Steps

1. Run `mkdir -p my-deeptutor && cd my-deeptutor`
2. Run `python -m pip install -U "deeptutor[full]"`
3. Run `deeptutor init` to set ports, the LLM provider and optional embedding and search
4. Run `deeptutor start` and open the printed URL, by default http://127.0.0.1:3782

### Prompt to paste into your agent

```text
Install DeepTutor with `python -m pip install -U "deeptutor[full]"` in a new my-deeptutor folder, run `deeptutor init` with <provider>, then `deeptutor start`, and confirm the web app opens.
```

### Caveat

Upgrading from 1.6.15 or earlier needs the legacy deeptutor-cli package removed first; see the migration guide.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/hkuds-deeptutor/install-deeptutor-with-pip/

## How to score which retrieval setup works best on your knowledge base with Deep Tutor

Repo: [HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) | Difficulty: Advanced | Time: 45 minutes | Basis: From the README

Write a small QA set and run deeptutor kb eval to get Recall, Precision, nDCG and MRR.

**Who it is for:** A teacher or researcher deciding how to index course material in Deep Tutor.

**The problem:** It is unclear which retrieval engine or mode actually finds the right passages for your documents.

**The outcome:** Saved metric reports you can compare per metric and per case.

### Steps

1. Write a QA set as JSON lines, each with a query and the gold passages an ideal retrieval should return
2. Run `deeptutor kb eval <name> --dataset qa.jsonl --top-k 5 [--mode hybrid] [--save baseline.json]`
3. Change the engine or mode and save a second report
4. Compare them with `deeptutor kb eval-diff baseline.json candidate.json`

### Prompt to paste into your agent

```text
For my DeepTutor knowledge base <name>, write 10 QA cases from these documents as qa.jsonl, run `deeptutor kb eval` with --top-k 5 and --save baseline.json, and summarize Recall@k and MRR.
```

### Caveat

Matching uses exact text or lexical overlap; semantic equivalence is not assessed, and PageIndex is excluded.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/hkuds-deeptutor/score-your-knowledge-base-retrieval/
