🤖 Humanoid AI Studio

AI-Native Educational Platform for Physical AI & Humanoid Robotics

---

What Is Humanoid AI Studio?

Humanoid AI Studio is a production-grade learning platform for Physical AI and Humanoid Robotics education. It delivers a 4-module interactive curriculum through a Docusaurus book, guided by an embedded RAG-powered chatbot that answers questions directly from the course content, with OAuth2 social login and AI-powered personalization.

The problem it solves:

• Static documentation sites have no AI layer — learners get stuck with no contextual help
• Robotics education content is scattered with no unified, progressive learning path
• No personalization — every learner gets the same experience regardless of language or background

How it works:

graph LR
    A[Student Signs Up] --> B[OAuth2 Login]
    B --> C[Module 1 Unlocked]
    C --> D{Learn via Book}
    D --> E[Ask RAG Chatbot]
    D --> F[Select Text → Ask About This]
    D --> G[Request Personalized Chapter]
    G --> H[Urdu or Custom Language]
    E --> I[Gemini Streams Response]
    I --> D
    D --> J[Module 2 → 3 → 4]
    J --> K[Capstone: Autonomous Humanoid]

Loading

---

🏗️ System Architecture

graph TB
    subgraph Client["Client Layer"]
        FE["Docusaurus Book\n(Netlify)"]
    end

    subgraph Auth["Auth Layer"]
        AUTH["Better-Auth OIDC Server\n(Railway · Node.js)"]
        JWKS["JWKS Endpoint\n/.well-known/jwks.json"]
    end

    subgraph API["API Layer"]
        BACKEND["FastAPI Backend\n(Railway · Python 3.11)"]
        MW["JWKS Middleware\nJWT Validation"]
    end

    subgraph AI["AI Layer"]
        RAG["RAG Pipeline\nQdrant + Sentence Transformers"]
        GEMINI["Google Gemini\nStreaming SSE"]
        PERSONALIZE["Personalization Agent\nUrdu / Custom Language"]
    end

    subgraph Data["Data Layer"]
        PG[("PostgreSQL\nNeon")]
        REDIS[("Redis\nCache + Rate Limit")]
        QDRANT[("Qdrant\nVector Store")]
    end

    FE -->|"OAuth / Session"| AUTH
    FE -->|"API Calls"| BACKEND
    AUTH --> JWKS
    AUTH --> PG
    BACKEND --> MW
    MW --> JWKS
    BACKEND --> RAG
    BACKEND --> PERSONALIZE
    BACKEND --> PG
    BACKEND --> REDIS
    RAG --> QDRANT
    RAG --> GEMINI

Loading

---

🔄 Request Flow

sequenceDiagram
    participant U as User
    participant FE as Docusaurus Book
    participant AUTH as Better-Auth OIDC
    participant API as FastAPI Backend
    participant AI as RAG / Gemini
    participant DB as Neon Postgres

    U->>FE: Visit Book
    FE->>AUTH: Sign In (Google / GitHub)
    AUTH-->>FE: JWT Access Token (RS256)
    FE->>API: Chat Request + Bearer Token
    API->>AUTH: Verify via JWKS endpoint
    AUTH-->>API: Token valid
    API->>DB: Fetch user session
    DB-->>API: Session data
    API->>AI: RAG query with curriculum context
    AI-->>API: Streamed response (SSE)
    API-->>FE: Response
    FE-->>U: Answer rendered in chat widget

Loading

---

🎓 4-Module Learning Path

graph LR
    S1["Module 1\nROS 2"]
    S2["Module 2\nSimulation"]
    S3["Module 3\nNVIDIA Isaac"]
    S4["Module 4\nVLA Capstone"]

    S1 --> S2
    S2 --> S3
    S3 --> S4

    style S1 fill:#3B82F6,color:#fff
    style S2 fill:#22C55E,color:#fff
    style S3 fill:#F97316,color:#fff
    style S4 fill:#EF4444,color:#fff

Loading

Each module builds on the previous. All lessons follow the Prediction → Execution → Reflection cycle and include executable code, observable outcomes, and debugging scenarios.

---

🛠️ Technology Stack

Frontend

Backend

Auth Server

AI & ML

Databases

Infrastructure

---

✨ Key Features

🤖 RAG Chatbot Google Gemini + SSE streaming responses Qdrant vector retrieval (cosine similarity) Sentence Transformers — local, free embeddings Text-selection triggered queries Full-book or selected-text search modes Rate limiting: 20 queries/hour per user	🔐 Authentication Better-Auth OIDC (RS256 JWT) Google + GitHub OAuth2 social login JWKS endpoint for token verification Secure cross-domain session management User profiles in Neon Postgres
🌐 AI Personalization Generate custom chapters on demand Urdu language support Translation endpoint for curriculum content Multi-agent skill pipeline orchestration	📡 Observability OpenTelemetry distributed tracing Prometheus metrics export Structured JSON logging Health check endpoints on all services Per-user rate limiting via Redis

---

🚀 Getting Started

Prerequisites

Tool	Version
Node.js	18+
Python	3.11+
Docker	Latest
Ubuntu	22.04 LTS (recommended)
GPU (Module 3+)	NVIDIA with 6GB+ VRAM

1. Clone

git clone https://github.com/ayeshakhalid192007-dev/humanoid-ai-studio.git
cd humanoid-ai-studio

2. Configure Environment

cp .env.example .env

Key values in .env:

GEMINI_API_KEY=your_gemini_key
OPENAI_API_KEY=your_openai_key_fallback
QDRANT_URL=https://your-cluster.qdrant.io
QDRANT_API_KEY=your_qdrant_key
DATABASE_URL=postgresql://user:pass@host/db
BETTER_AUTH_SECRET=your_secret
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
CORS_ORIGINS=http://localhost:3000
RATE_LIMIT_QUERIES_PER_HOUR=20

3. Start Auth Server

cd auth-server && npm install && npm start
# Runs on http://localhost:3002

4. Start Backend API

cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
# API docs: http://localhost:8000/docs

5. Start the Book

cd book && npm install && npm start
# Runs on http://localhost:3000

For detailed setup, see quickstart.md

---

🤖 AI Agent Architecture (gitagent)

Humanoid AI Studio uses gitagent — a framework-agnostic, git-native standard for defining AI agents. The agent is version-controlled alongside the codebase, exportable to any LLM framework, and composable across skills.

# Export the agent as a system prompt (works with any LLM)
npx gitagent export --format system-prompt

# Export as Claude Code CLAUDE.md
npx gitagent export --format claude-code

# Validate agent configuration
npx gitagent validate

# View agent info
npx gitagent info

Agent Structure

graph TB
    subgraph Agent["humanoid-ai-studio agent"]
        SOUL["SOUL.md\nAria — AI tutor identity"]
        RULES["RULES.md\nSafety & content boundaries"]
        AGENTS["AGENTS.md\nSub-agent delegation map"]
        YAML["agent.yaml\nModel, skills, runtime config"]
    end

    subgraph Skills["skills/"]
        S1["rag-tutor\nCurriculum Q&A via Qdrant"]
        S2["personalize-chapter\nAdaptive chapter generation"]
        S3["translate-urdu\nRTL Urdu translation"]
        S4["ros2-guide\nROS 2 Humble step-by-step"]
        S5["code-explainer\nRobotics code walkthrough"]
    end

    subgraph Knowledge["knowledge/"]
        K["index.yaml\nCurriculum + spec document registry"]
    end

    YAML --> Skills
    SOUL --> YAML
    RULES --> YAML
    AGENTS --> YAML
    Skills --> Knowledge

Loading

Skills

Skill	Purpose	Trigger
rag-tutor	Answers curriculum questions via Qdrant + Gemini RAG	Any factual robotics question
personalize-chapter	Rewrites chapters for learner's background + language	"Personalize this chapter"
translate-urdu	Translates prose to Urdu RTL, preserves all code	"Translate to Urdu"
ros2-guide	Step-by-step ROS 2 Humble Hawksbill guidance	ROS 2 how-to questions
code-explainer	Explains robotics Python/YAML/SDF code line by line	"Explain this code" / debug requests

Sub-Agents

graph LR
    O["Orchestrator\nhumanoid-ai-studio"]
    O -->|"curriculum question"| R["rag-tutor\nQdrant + Gemini SSE"]
    O -->|"personalize request"| P["personalization-agent\nProfile + RAG + Gemini"]
    O -->|"translate request"| T["translation-agent\nUrdu RTL output"]
    O -->|"auth / session"| A["auth-agent\nBetter-Auth OIDC"]

Loading

---

📁 Project Structure

humanoid-ai-studio/
├── book/                    # Docusaurus 3 frontend (React, TypeScript, Tailwind)
│   ├── docs/                # Curriculum markdown (modules 1–4, capstone)
│   └── src/                 # React components, pages, context, plugins
│
├── backend/                 # FastAPI RAG backend (Python 3.11)
│   ├── src/
│   │   ├── api/             # Endpoints: chat, personalize, translate, sessions, auth
│   │   ├── ai/              # Gemini client, orchestrator, RAG/personalization agents
│   │   ├── db/              # Qdrant (vector) + Neon Postgres clients
│   │   ├── models/          # Pydantic schemas
│   │   └── utils/           # Logging, monitoring, rate limiting
│   └── main.py              # FastAPI app entry point
│
├── auth-server/             # Better Auth server (Node.js, Express)
│   └── src/
│       ├── index.js         # Express + Better Auth setup
│       └── auth.js          # OAuth2/OIDC authentication logic
│
├── agent.yaml               # gitagent manifest — model, skills, runtime config
├── SOUL.md                  # Agent identity (Aria — the AI tutor)
├── RULES.md                 # Agent safety and content boundaries
├── AGENTS.md                # Sub-agent delegation architecture
├── skills/                  # Reusable AI skill modules (rag-tutor, ros2-guide, etc.)
├── knowledge/               # Curriculum document registry for RAG
├── specs/                   # SDD-RI feature specs (spec.md, plan.md, tasks.md)
├── history/                 # Prompt History Records + Architecture Decision Records
└── .specify/                # SDD templates, scripts, project constitution

---

🧪 Testing

Backend

cd backend
pytest

Book (Frontend)

cd book
npm run build    # type-check + production build

Standard testing environment:

• OS: Ubuntu 22.04 LTS
• ROS 2: Humble Hawksbill
• Gazebo: Gazebo 11 (Module 2)
• Isaac Sim: NVIDIA Isaac Sim 2023.1.1 (Module 3)

---

🚢 Deployment

All deployments are automated via GitHub Actions on push to main:

Workflow	Path Trigger	Target
deploy-book.yml	book/**	Netlify
deploy-backend.yml	backend/**	Railway
deploy-auth.yml	auth-server/**	Railway

Required GitHub Secrets: RAILWAY_TOKEN, NETLIFY_SITE_ID, NETLIFY_AUTH_TOKEN

---

📊 Implementation Progress

Auth & OAuth2 Login      ████████████████████  Complete
RAG Chatbot              ████████████████████  Complete
Module 1 — ROS 2         ████████████████████  Complete
Module 2 — Simulation    ████████████████████  Complete
Module 3 — NVIDIA Isaac  ████████████████████  Complete
Module 4 — VLA Capstone  ████████████████████  Complete
AI Personalization       ████████████████████  Complete
Observability            ████████████████████  Complete
CI/CD Deployment         ████████████████████  Complete

---

🤝 Contributing

1. Fork the repository and create a branch: git checkout -b feature/<name>
2. Follow SDD-RI: Specify → Plan → Implement → Validate
3. All Python-ROS 2 bridges must be reusable and documented
4. Validate in the Standard Testing Environment before opening a PR

Code Standards: Python — PEP 8, type hints, async-first · TypeScript — strict mode · React — functional components only · All changes must include observable outcome verification

---

📄 License

MIT — see LICENSE

---

Contact

Maintainer contact information and community links to be added.

Constitution Version: 1.2.0 | Last Updated: 2026-03-27

---

DEVELOP AND DEPLOY THIS SO IT WILL BE BENEFICIAL FOR EVERYONE