Humanoid Robotics Textbook: a RAG-powered textbook you can question, not just read
Static textbooks answer in chapters; students ask in sentences. The Humanoid Robotics Textbook is an interactive course on Physical AI — ROS 2, digital twins, NVIDIA Isaac, vision-language-action models — whose chapters are embedded into a vector database so a question finds the right passage by meaning, and whose reader can highlight any paragraph and ask about exactly that. It answers from the book, and says so when the book doesn't cover it.
- Type
- EdTech · interactive textbook · RAG tutor
- Stack
- Docusaurus · Next.js · FastAPI · Qdrant · OpenAI Agents SDK
- Search
- Semantic — chapter chunks in Qdrant, cited by chapter and heading
- Status
- Live at humanoid-robotics-textbook.vercel.app
The problem: learners don't know the vocabulary yet
Technical curriculum lives in long-form documents, but learners arrive with specific questions — “why does a node publish to a topic instead of just calling the other node?” — that a table of contents can't route. Keyword search fails the same way: a student who doesn't yet know the word “publisher” can't search for it, and not knowing the words is precisely why they're reading.
The second failure is subtler. A chatbot bolted onto a textbook will happily answer from its general training, which for robotics means confident, plausible, and sometimes wrong — and the student has no way to tell. A tutor for a textbook has to answer from the textbook, show where, and admit when the book is silent.
What the book covers
The textbook is Physical AI & Humanoid Robotics — “from digital intelligence to embodied reality” — planned as four modules: the Robotic Nervous System (ROS 2), the Digital Twin (Gazebo and Unity), the AI-Robot Brain (NVIDIA Isaac), and Vision-Language-Action models. Module 1 is published — an introduction to ROS 2, nodes, topics and publishers — along with a ROS 2 services module that walks from the concept of a service through creating a server and a client to using them in practice.
Chapters are authored in Docusaurus with Mermaid diagrams, and the module carries its own code-quality and diagram-colour standards pages, because a textbook that teaches conventions should follow visible ones. A Next.js landing page fronts the whole thing and hands off to the Docusaurus site.
Retrieval that answers from the book, or not at all
Every chapter is chunked and embedded into Qdrant, with each chunk carrying its chapter title, URL slug, and section heading as payload. When a student asks the chat a question, a FastAPI backend embeds the question, searches Qdrant for the nearest passages — optionally filtered to the chapter the student is reading — and builds a prompt from those passages alone. The model behind it is Gemini, driven through the OpenAI Agents SDK via an OpenAI-compatible endpoint, with instructions to act as a tutor for this textbook using only the provided context.
The answer comes back with the retrieved passages attached, so the interface can show where in the book it came from rather than asking the student to trust it. And when the search returns nothing relevant, the system doesn't improvise: it says it could not find anything in the textbook related to the question. That refusal is the feature. A textbook tutor that answers questions the textbook doesn't cover is just a chatbot with a robotics logo.
Ask about this paragraph
The interaction I'm most pleased with is the smallest. Highlight any passage in a chapter and a button appears; tap it and a modal opens with the selected text already loaded, asking what you want to know about it. The question goes to a dedicated endpoint that receives the exact selection plus the student's question, so the answer is anchored to the sentence that confused them rather than to a search over the whole book.
It exists because that's how people actually read hard material: not “explain ROS 2 services” but “what does this sentence mean?”. The selection state is captured before the modal opens — a detail that matters, because opening a dialog collapses the browser selection, and the naive version loses the very text it was about to ask about.
Running Python and React on one Vercel deployment
The whole system deploys to Vercel: the Next.js landing page and the FastAPI backend run as serverless functions side by side, with the Docusaurus build served as static pages. Serverless shaped the backend — the Qdrant client is created lazily on first request rather than at import time, so cold starts don't pay for a connection they may not use, and every endpoint is registered under both its bare path and an /api prefix because the platform routes to the function without stripping it.
The vector database is Qdrant Cloud, so nothing stateful lives in the deployment itself: redeploying the site never touches the index, and re-embedding the book is a separate job from shipping a chapter. Requests and responses are validated with Pydantic models, and errors return as explicit HTTP statuses — an embedding failure, a search failure, and a generation failure are three different problems and are reported as three different errors.
Honest limits
Module 1 and the services module are the content that exists today; the digital-twin, Isaac, and VLA modules are outlined in the introduction and not yet written, and the retrieval is only as good as the chapters that exist. The chat has no evaluation harness yet — unlike my compliance and support RAG systems, I haven't measured retrieval accuracy here against a labelled question set, so I describe the mechanism rather than quote a number.
What I'd do next, in order: write the remaining modules, then build the eval set from real student questions, then tune chunking against it. The chunk-embed-retrieve pipeline is the same foundation I use in production RAG systems; the difference is that this one has students on the other end, and a wrong answer costs them a misconception rather than a compliance finding.