An open-source, interactive AI tutor that helps you think and solve problems yourself, instead of just handing you the answers.
Watch Guidey pace lessons in real-time on a digital blackboard with LaTeX typesetting and progressive hints.
Try Live Demo (No Signup Required) · Explore Open Issues · Join Discussions
Most AI tutoring tools are just thin prompt wrappers over generic LLMs. You ask a question, and they immediately dump 5 paragraphs of the final answer or solve your entire assignment for you.
The result is cognitive decay: students and engineers submit code and homework they do not understand, bypassing the struggle where actual learning happens.
Guidey fixes that by acting like an experienced professor sitting next to you:
- Progressive Socratic Scaffolding: It diagnoses your frontier of knowledge and provides small, targeted hints instead of spoiling the solution.
- Anti-Monologue Guardrails: Keeps responses concise and conversational, asking you probing questions to guide your next step.
- Interactive Digital Blackboard: Renders hand-drawn procedural chalk margins (Rough.js), LaTeX math typesetting (KaTeX), and interactive visual simulators.
- Embodied 3D Instructor: Three.js GLTF-driven professor avatar with synchronized gestures, gaze tracking, and real-time speech narration.
- 100% Free & Open Source: Full-stack Next.js 14 frontend + FastAPI backend. Run it locally or self-host without proprietary vendor lock-in.
┌─────────────────────────────────────────────────────────────┐
│ Next.js 14 Frontend │
│ ┌───────────────────────┐ ┌───────────────────────┐ │
│ │ Interactive Tutor │ │ 3D Canvas Avatar │ │
│ │ Chalkboard (KaTeX) │ │ (Three.js/GLTF) │ │
│ └───────────┬───────────┘ └───────────┬───────────┘ │
│ │ │ │
│ └───────────────┬───────────────┘ │
│ │ WebSocket / REST │
└──────────────────────────────┼──────────────────────────────┘
│
┌──────────────────────────────▼──────────────────────────────┐
│ FastAPI Backend │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Unified Professor Agent │ │
│ │ - Pedagogical Intent & Archetype Classifier │ │
│ │ - Socratic Pacing & Lesson Planner │ │
│ │ - Semantic Board Spec & Gesture Emitter │ │
│ └───────────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌──────────────────────┼──────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌─────────────┐ ┌────────────┐ │
│ │ Curriculum │ │ Student │ │ Background │ │
│ │ Hub │ │ Mastery DB │ │ TTS Engine │ │
│ └────────────┘ └─────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────┘
- Archetype & Pedagogical Classifier (
pedagogical_classifier.py): Dynamically classifies learner intent into archetypes (Conceptual, Procedural, Diagnostic, Exam Prep, Troubleshooting) to modulate tone, hint depth, and board pacing. - Semantic Board Specification: In a single pass, the professor agent outputs structured JSON specifying:
- Speech segments for progressive narration.
- Board layout elements (
heading,body,margin,scratchpad). - Procedural chalk overlays (
encircle,strikethrough,box,highlight,underline). - Curved Bézier arrows linking interdependent concepts.
- Active Comprehension Probes: Embeds diagnostic check-ins and checks your understanding before advancing to higher-order topics.
-
Chalkboard Themes (
Whiteboard.tsx): Procedural blackboard styles in Emerald, Slate, and Ocean powered by Rough.js. -
Native KaTeX LaTeX Support: Crisp rendering of mathematical equations, derivations, matrices, and notation (
$$\int_a^b f(x)dx$$ ,$$\sum_{i=1}^n x_i$$ ). -
3D Embodied Avatar (
Avatar3D.tsx): Three.js GLTF avatar with gesture switching, coordinate pointing, and responsive posture. - Direct Concept Simulators: Interactive sandbox components allowing learners to manipulate parameters and test hypotheses.
- Python 3.10+
- Node.js 18+ &
npm - An API key for Google Gemini, OpenAI, or Ollama
start.batcd backend
python -m venv venv
# On Windows:
venv\Scripts\activate
# On Linux/macOS:
# source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # Add your API key
uvicorn server:app --reload --host 127.0.0.1 --port 8000Backend API will be live at http://localhost:8000 (Swagger docs: http://localhost:8000/docs).
cd frontend
npm install
npm run devOpen http://localhost:3000/tutor in your browser.
We welcome contributions from developers, educators, and researchers of all experience levels!
Check out our curated issue backlog:
- Good First Issues: Beginner-friendly tickets to get started.
- Help Wanted: Feature requests and architecture enhancements.
Key areas currently open:
- Issue #4: Pluggable multi-provider LLM abstraction layer (Ollama, vLLM, Groq).
- Issue #5: Dynamic model selection and custom LLM parameter controls.
- Issue #11: Responsive blackboard viewport layout and mobile touch support.
- Issue #12: Modular service refactoring for session management.
- Issue #10: Infinite blackboard canvas and procedural scientific diagrams.
Read our Contributing Guide to submit your first Pull Request.
This project is licensed under the MIT License — free for personal, academic, and commercial use.