wendao 0.1.0

Wendao (问道, wèn dào, "asking the way") is an AI learning companion. It turns your course materials into two things for students:

• an interactive knowledge graph of the course's chapters and concepts, and
• an AI learning agent that answers questions using only the course materials, with a link to the page each answer came from.

It was built for the NUS course MLE4217/5219 Materials Informatics, and this repository uses that course as its example. Nothing in the code is tied to that course, so you can run it on any course written as Markdown pages and Jupyter notebooks.

More docs: developer notes · student guide · product plan

How it works

1. Extract. Wendao reads your course pages and notebooks and splits them into small pieces called chunks.
2. Knowledge graph. Chapters and concepts become nodes. Two nodes are linked only when they appear together in the course.
3. Search. When a student asks a question, Wendao finds the most relevant chunks. It combines keyword search with meaning-based search. If the chunks don't really answer the question, Wendao says so instead of guessing.
4. Answer. The chunks it found are sent to a language model (Claude, GPT, Gemini, or a local model), which writes the answer. No model training or GPU is needed.

Demo

Knowledge graph

Blue nodes are chapters and orange nodes are concepts. Click a chapter to see its concepts, or click a concept to see every chapter that uses it. You can also filter with the legend or search.

_{Full-resolution video: knowledge_graph_demo.mp4}

AI learning agent

Select a node and press Explain, or pick one of the suggested questions. You can ask follow-up questions and open the cited course page from the answer. If the course doesn't cover a question, the agent tells you.

_{Full-resolution video: ai_learning_agent_demo.mp4}

Why use it

Students can explore the course in any order, see how topics connect, and check their understanding. The agent only answers from the course, and it says clearly when it can't.

Instructors can reuse Wendao for their own course. You only need your course content and a list of concepts. Only the chunks relevant to each question are sent to the model, and any major model provider works. Test questions let you check what the agent will and won't answer before students use it.

Install

You need Python 3.11 or newer and curl. Install the wendao command with uv:

uv tool install wendao

Or with pip:

pip install wendao

Check it works with wendao --help.

How you work with Wendao

Wendao is the tool. Your course lives in its own folder, called a workspace, next to your lecture notes:

my-course/
  notes/            your lecture notes: Markdown pages and Jupyter notebooks (or point to a folder elsewhere)
  wendao.toml        course name, website, chapters, and which model to use
  concepts.json     the concepts to show in the knowledge graph
  questions.json    test questions
  .env              your API key (never committed)
  build/            files Wendao creates: chunks, graph, search index, reports

Run wendao commands anywhere inside the workspace. Wendao finds wendao.toml by itself.

Run any command with --help to see its options.

Quick start: try the example course

The repository includes a ready-built workspace for MLE4217/5219:

git clone https://github.com/deng-group/wendao.git
cd wendao/examples/mle4217_5219
wendao ask --search-only "What is a convex hull?"    # works without a model

To get real answers, set [model] in wendao.toml to your own provider and put its key in .env (see Connect a model). Then run wendao serve. It checks the model connection, starts Wendao at http://127.0.0.1:5057/, and opens it in your browser. Press Ctrl+C to stop.

Use Wendao for your own course

1. Create a workspace

wendao init my-course                              # creates my-course/ with a notes/ folder
wendao init my-course --source ~/teaching/notes    # or use notes you already have
cd my-course

Your notes should be Markdown (or MyST) pages and Jupyter notebooks, such as a Jupyter Book. Each top-level folder becomes a chapter.

2. Describe your course

Open wendao.toml and fill in the course name and website. The website lets answers link to the right page. The file explains each setting. The most useful ones are:

• [[chapters]]: names, order, and visibility for your chapter folders. Folders you don't list still appear, named after the folder.
• [search] aliases: spellings students might type, such as { "convexhull" = "convex hull" }.
• [graph] bridge_stop_concepts: very common concepts, such as python, that shouldn't link chapters on their own.

Then list the concepts for the knowledge graph in concepts.json. For each concept, give the words to look for in your notes:

{"id": "convex-hull", "label": "Convex Hull", "category": "thermodynamics", "aliases": ["convex hull", "convex hulls"]}

See examples/mle4217_5219/ for a complete example.

3. Build

wendao build

This reads your notes, builds the knowledge graph, and builds the search index. The first run downloads the search model. Run it again whenever you change your notes or settings.

Check the search results before you connect a model:

wendao ask --search-only "What is a convex hull?"

This shows the pages search found and whether Wendao thinks it can answer.

4. Connect a model

Wendao works with three kinds of API. Choose one in wendao.toml and put its key in .env:

For example, for a local model with Ollama, which needs no key:

[model]
provider = "openai"
model = "llama3.1"
base_url = "http://localhost:11434/v1"

Then test it:

wendao check
wendao ask "How is Materials Project data used to train MACE potentials?"

A small, cheap model is usually enough, because Wendao gives it the relevant course text. Answers use a temperature of 0.2. Some models, such as OpenAI's reasoning models, don't accept one; set temperature = "none" under [model] for those.

5. Run it

wendao serve

To put Wendao on a server, see deploy/DEPLOYMENT.md. To add the agent to your course website as a chat widget, run wendao serve --widget and see README_DEVELOPERS.md.

Testing your agent

Add real questions from your course to questions.json. For each one you can say what Wendao should do:

{
  "id": "convex_hull",
  "query": "What is a convex hull?",
  "expected_status": "answerable",
  "expected_files": ["high_throughput/thermodynamics.md"]
}

expected_status is one of answerable, needs_time_context (schedule questions), needs_clarification (too broad), weak_evidence (not enough in the notes), or out_of_scope. Then run:

wendao eval             # search and answer decisions, no model needed
wendao eval --answers   # prompts and citations, no model needed
wendao eval --real      # ask the real model every question, so you can read the answers (uses API credits)

Reports are saved in build/reports/.

Developing Wendao

git clone https://github.com/deng-group/wendao.git
cd wendao
uv sync --all-extras                       # creates .venv with the locked versions, `wendao` included
uv run python -m unittest discover -s tests

Citation

Wendao is developed by the Deng group in the Department of Materials Science and Engineering at the National University of Singapore, for MLE4217/5219 Materials Informatics. If you use Wendao or adapt it for your own course, please cite this repository:

@software{wendao2026,
  author = {Deng, Zeyu and contributors},
  title  = {Wendao: an AI learning companion with an interactive course knowledge graph},
  year   = {2026},
  url    = {https://github.com/deng-group/wendao}
}

License

Wendao is free software under the GNU General Public License v3.0 or later. You can use, study, change, and share it. If you share a changed version, you must share its source code under the same license.