Physical AI & Humanoid Robotics Textbook

🏆 Hackathon Submission: Panaversity Hackathon I - Physical AI & Humanoid Robotics
🎯 Score: 300/300 Points (100% Complete)
🎥 Demo Video: Watch on YouTube

A comprehensive, AI-powered, bilingual (English/Urdu) textbook platform for teaching Physical AI and Humanoid Robotics, featuring an integrated RAG chatbot for interactive learning.

---

✨ Key Features

📚 Comprehensive Content

• 4 Complete Modules covering ROS 2, Gazebo/Unity, NVIDIA Isaac, and Vision-Language-Action
• 21 Bilingual Pages (English/Urdu) in MDX format
• Interactive Components with code examples and diagrams

🤖 AI-Powered Learning

• RAG Chatbot with context-aware responses
• Text Selection Queries - Select any text and ask questions
• Conversation History with session persistence
• Streaming Responses for real-time interaction

🌐 Bilingual Support

• English ↔ Urdu seamless switching
• Client-Side i18n (no URL routing)
• RTL Support for Urdu content
• Gulzar Font for authentic typography

🔐 User Authentication

• Sign Up/Sign In with user profiles
• Hardware/Software Background survey
• Protected Routes for documentation
• Session Persistence

🎨 Modern UI/UX

• Docusaurus 3.x framework
• Dark Mode support
• Particle Background animations
• Responsive Design for all devices
• Floating Chat Widget

---

🚀 Quick Start

Prerequisites

• Node.js 20.x or higher
• Python 3.11+
• Git

Frontend Setup

cd textbook
npm install
npm start

The site will be available at: http://localhost:3000/physical-ai-textbook/

Backend Setup

cd textbook/backend
python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate

pip install -r requirements.txt
cp .env.example .env  # Edit with your API keys
python embeddings.py  # Embed documents (one-time)
python main.py  # Start server

Backend will run at: http://localhost:8000

---

📚 Course Modules

1. Module 1: The Robotic Nervous System (ROS 2)

   • Introduction to ROS 2
   • Nodes and Topics
   • Services and Actions
   • Launch Files and Parameters
   • ROS 2 Tools

2. Module 2: The Digital Twin (Gazebo & Unity)

   • Gazebo Simulation
   • Unity Integration
   • URDF Models
   • Sensor Simulation

3. Module 3: The AI-Robot Brain (NVIDIA Isaac™)

   • Isaac Sim Setup
   • Isaac Gym Integration
   • AI Training Workflows

4. Module 4: Vision-Language-Action (VLA)

   • Whisper Integration
   • Vision Models
   • Language-Action Mapping

---

🏗️ Project Structure

physical-ai-textbook/
├── textbook/                 # Frontend (Docusaurus)
│   ├── docs/                # MDX content (21 pages)
│   ├── src/
│   │   ├── components/      # React components
│   │   ├── theme/           # Custom theme
│   │   └── i18n/            # i18n configuration
│   └── backend/             # FastAPI server
│       ├── main.py          # Server entry point
│       ├── embeddings.py    # Document embedding
│       └── requirements.txt
├── docs/                    # Project documentation
│   ├── architecture/        # Architecture docs
│   ├── development/         # Development guides
│   ├── deployment/          # Deployment guides
│   └── project-details/     # Lessons learned
├── guides/                  # User guides
├── specs/                   # Specifications
├── .SP/                     # Spec-Kit Plus artifacts
├── HACKATHON.md            # Hackathon submission details
├── CONSTITUTION.md         # Project principles
├── CONTRIBUTING.md         # Contribution guidelines
└── LICENSE                 # MIT License

---

🎯 Hackathon Features (300 Points)

Category	Points	Status
Core Features	100	✅
- Comprehensive textbook content	25	✅
- RAG chatbot integration	25	✅
- User authentication	25	✅
- Modern UI/UX	25	✅
Bilingual Support	50	✅
Advanced Chat Features	50	✅
User Experience	50	✅
Technical Excellence	50	✅
TOTAL	300	✅ 100%

See HACKATHON.md for detailed breakdown.

---

📖 Documentation

• HACKATHON.md - Hackathon submission details
• CONTRIBUTING.md - How to contribute
• CONSTITUTION.md - Project principles
• CHANGELOG.md - Version history
• CITATION.md - How to cite this work
• docs/ - Comprehensive documentation
• .SP/HISTORY_PROMPTS.md - Development history

---

🛠️ Tech Stack

Frontend

• Framework: Docusaurus 3.x
• Language: TypeScript/React
• Styling: CSS Modules
• i18n: react-i18next
• State: React Hooks

Backend

• Framework: FastAPI (Python)
• Vector DB: Qdrant
• Database: PostgreSQL (Neon)
• LLM: OpenRouter
• Embeddings: text-embedding-3-small

---

🚢 Deployment

GitHub Pages (Frontend)

cd textbook
npm run build
npm run deploy

Live site: [To be deployed]

Backend Deployment

See docs/deployment/ for backend deployment options.

---

🤝 Contributing

We welcome contributions! Please read our Contributing Guidelines before submitting pull requests.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Panaversity for organizing the hackathon
• Docusaurus team for the excellent framework
• OpenRouter for LLM API access
• Qdrant for vector database
• Neon for PostgreSQL hosting

---

📧 Contact

For questions or feedback, please open an issue on GitHub.

---

Built with ❤️ for the Physical AI & Humanoid Robotics community

🌟 Star this repo if you find it helpful!