Master the complete technology stack for building intelligent humanoid robots — from ROS 2 fundamentals to Vision-Language-Action models — with an AI assistant that learns from the textbook itself.
This isn't just a textbook — it's a full-stack educational platform where students learn Physical AI & Humanoid Robotics through four progressive modules, guided by a RAG-powered AI chatbot that understands every page of the book.
Select any paragraph. Click AI Assistant. Ask "explain this". Get an answer grounded in the textbook content, with source citations back to the exact lesson.
| Feature | Description |
|---|---|
| RAG Chatbot | Ask questions in natural language — answers are retrieved from the textbook's vector-indexed content |
| Highlight & Ask | Select text on any page, click the floating AI button, and get context-aware explanations |
| Source Citations | Every answer references the module, lesson, and section it came from |
| Conversation Memory | Multi-turn conversations with up to 5 messages of context, persisted for 7 days |
| 4 Progressive Modules | From ROS 2 basics to cutting-edge VLA models — a complete robotics curriculum |
| Dark Mode | Designed for comfortable reading during long study sessions |
Module 1 ─ The Robotic Nervous System (ROS 2)
│ Nodes, topics, pub/sub, URDF, launch files
│
Module 2 ─ Sensors & Perception
│ Cameras, LiDAR, IMU, depth sensing, sensor fusion
│
Module 3 ─ The AI-Robot Brain (NVIDIA Isaac)
│ Isaac Sim, synthetic data, Nav2, autonomous navigation
│
Module 4 ─ Vision-Language-Action Models
Foundation models, VLAs, end-to-end autonomous behavior
Each lesson follows a structured format: Concept → Why It Matters → Key Principles → Hands-On Example → Summary → Next Steps — with AI colearning prompts and practice exercises throughout.
┌─────────────────────────────────────────────────────────┐
│ GitHub Pages │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Docusaurus v3 (React / TypeScript) │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────────┐ ┌───────────┐ │ │
│ │ │ MDX Docs │ │ AI Chat UI │ │ Text │ │ │
│ │ │ (4 mods) │ │ (ChatInterface│ │ Selection │ │ │
│ │ │ │ │ + hooks) │ │ Hook │ │ │
│ │ └──────────┘ └──────┬───────┘ └─────────────┘ │ │
│ └────────────────────────┼────────────────────────────┘ │
└────────────────────────────┼───────────────────────────────┘
│ REST API
▼
┌─────────────────────────────────────────────────────────┐
│ FastAPI Backend (Hugging Face Spaces) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Rate │───▶│ RAG │───▶│ OpenRouter │ │
│ │ Limiter │ │ Service │ │ (LLM Generation) │ │
│ └──────────┘ └────┬─────┘ └──────────────────┘ │
│ │ │
│ ┌─────────┴─────────┐ │
│ ▼ ▼ │
│ ┌──────────────────┐ ┌────────────────┐ │
│ │ Cohere Embeddings│ │ Qdrant Cloud │ │
│ │ (v3.0 / 1024d) │ │ (Vector Store) │ │
│ └──────────────────┘ └────────────────┘ │
└─────────────────────────────────────────────────────────┘
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Docusaurus v3 + React 19 | Static site generation, interactive UI |
| Language | TypeScript 5.6 / Python 3.11+ | Type-safe frontend & backend |
| Backend | FastAPI | Async REST API for RAG pipeline |
| LLM | OpenRouter | Response generation |
| Embeddings | Cohere embed-english-v3.0 | 1024-dim semantic vectors |
| Vector DB | Qdrant Cloud | Similarity search over textbook chunks |
| Database | Neon Serverless Postgres | Conversation storage |
| Containerization | Docker | Reproducible backend deploys |
| CI/CD | GitHub Actions | Auto-deploy frontend (Pages) & backend (HF Spaces) |
- Node.js >= 20.0 and npm
- Python >= 3.11
- Git
git clone https://github.com/anusbutt/Physical-AI-Humanoid-Robotics-Textbook.git
cd Physical-AI-Humanoid-Robotics-Textbook/book-source
npm install
npm startOpens at http://localhost:3000.
cd backend
# Create .env with required keys (see .env.example)
# OPENROUTER_API_KEY, COHERE_API_KEY, QDRANT_URL, QDRANT_API_KEY, NEON_DATABASE_URL
pip install -r requirements.txt
uvicorn app.main:app --reload --port 7860API docs at http://localhost:7860/docs.
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/chat/query |
Send a question through the RAG pipeline |
POST |
/api/chat/feedback |
Submit feedback on a conversation |
GET |
/api/health |
Health check |
Physical-AI-Humanoid-Robotics-Textbook/
├── book-source/ # Docusaurus frontend
│ ├── docs/ # MDX textbook content (4 modules)
│ ├── src/
│ │ ├── components/ # ChatInterface, ChatInput, ChatMessage
│ │ ├── hooks/ # useChatState, useTextSelection
│ │ └── theme/ # Root.tsx (global chat button)
│ ├── static/ # Images & diagrams
│ └── docusaurus.config.ts
│
├── backend/ # FastAPI RAG backend
│ ├── app/
│ │ ├── api/chat.py # REST endpoints
│ │ ├── services/
│ │ │ ├── rag_service.py # RAG orchestration
│ │ │ ├── cohere_service.py # Embedding generation
│ │ │ └── qdrant_service.py # Vector search
│ │ ├── middleware/ # Rate limiting, error handling
│ │ ├── models/schemas.py # Pydantic data models
│ │ └── config/settings.py # Environment configuration
│ ├── Dockerfile
│ └── requirements.txt
│
├── .github/workflows/ # CI/CD pipelines
│ ├── deploy.yml # Frontend → GitHub Pages
│ └── deploy-hf-space.yml # Backend → Hugging Face Spaces
│
└── specs/ # Feature specifications (SDD)
This project follows Spec-Driven Development (SDD):
- Specification first, implementation second
- Testable acceptance criteria for every feature
- Architectural Decision Records for significant choices
- Small, incremental, testable changes
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing-feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Developer: Anus Butt
Originally built for Panaversity Hackathon.
This project is licensed under the MIT License. See LICENSE for details.
Built with Docusaurus, FastAPI, OpenRouter, Cohere & Qdrant