🎮 LearnPlay AI — Full Installation & Usage Guide Make Hard Concepts Feel Like Play
📘 Introduction LearnPlay AI is a local, privacy-friendly learning assistant powered by Ollama and built with Node.js + React. This guide will walk you through EVERYTHING you need — installing dependencies, downloading models, running backend, running frontend, uploading documents, generating quizzes, and more. ✅ Prerequisites Before you begin, ensure you have the following installed: • Node.js (v18 or higher recommended) • NPM (comes with Node.js) • Ollama (for local LLMs) • Git (optional but recommended) 🧠 Step 1 — Install Ollama Ollama is required to run local LLMs. Download from: https://ollama.com/download
After installation, open your terminal and verify: ollama --version
📥 Step 2 — Download Required Models LearnPlay requires 2 models:
- LLM model → llama3.2:3b
- Embedding model → nomic-embed-text
Run these commands: ollama pull llama3.2:3b ollama pull nomic-embed-text
📁 Project Folder Structure learnplay/ ├── client/ (React frontend) ├── server/ (Node.js backend) ├── README.md
🟦 Step 3 — Install Server Dependencies Navigate into the server folder: cd server
Install all required dependencies: npm install
This installs packages like: • express • cors • multer • pdf-parse • mammoth • dotenv
⚙️ Step 4 — Create .env File Inside /server create a file named .env with: PORT=5179 OLLAMA_URL=http://localhost:11434 OLLAMA_MODEL=llama3.2:3b
You should see: Server running → http://localhost:5179
⚛️ Step 6 — Install Frontend Dependencies Navigate to the client folder: cd client
Install packages: npm install
This installs React, Vite, and all UI dependencies.
🚀 Step 7 — Start the LearnPlay Frontend Run the frontend UI: npm run dev
You should now see LearnPlay running at: http://localhost:5173
🎓 Step 8 — Using LearnPlay AI ✅ Type a topic in the Topic box (e.g., 'Eigenvalues') ✅ Click: • Teach Me — explanation with analogy + example + check question • Co-Relate — relate to badminton/cooking • Quiz Me — generates quiz (JSON hidden) as UI • Make It Fun — story-mode explanation
📄 Step 9 — Uploading Documents (PDF/DOCX/TXT) Click the Upload button in the Topic panel and upload: • PDF file • DOCX file • TXT file
LearnPlay will: ✅ Extract text ✅ Chunk it ✅ Embed it using nomic-embed-text ✅ Enable document mode Now all buttons use ONLY the uploaded document content.
🎯 Step 10 — Quiz Mode (Document or Topic) When clicking 'Quiz Me': ✅ LearnPlay generates 3 questions ✅ JSON is parsed silently (NOT shown to user) ✅ Quiz UI appears below chat ✅ Answers are auto-graded ✅ Score is tracked persistently
🧹 Step 11 — Clear Document Context Click the Clear button to switch back to topic mode. This resets: • Document chunks • Embeddings • Quiz data
🛠️ Troubleshooting ✅ If Vite throws HTML parse errors → remove React syntax from index.html ✅ If Node crashes with memory error → update Node to v20+ ✅ If Ollama model errors → re-run: ollama pull llama3.2:3b ollama pull nomic-embed-text
✨ You Are Ready! Your LearnPlay AI setup is complete. Enjoy fun, interactive, document-powered learning!