SETUP.md

🚀 SETUP.md — MultiMind Classroom Setup Guide

Complete beginner-friendly guide to install, configure, run, and use MultiMind Classroom. Includes cost-effective AI model recommendations for every feature.

---

📋 Table of Contents

1. Prerequisites
2. Installation (Step by Step)
3. Running the App
4. Configuration — Which API Keys Do I Need?
5. Best & Most Cost-Effective AI Models
6. Feature-by-Feature Setup
7. Free Tier & Zero-Cost Options
8. Recommended Starter Configurations
9. Docker Deployment
10. Troubleshooting
11. FAQ

---

1. Prerequisites

Requirement	Minimum	Recommended
Node.js	20.9.0+	22.x LTS
npm or pnpm	npm 10+ or pnpm 10+	pnpm (faster)
OS	Windows 10+, macOS 12+, Linux	Any modern OS
RAM	4 GB	8 GB+
Browser	Chrome 100+, Firefox 100+, Edge 100+, Safari 16+	Chrome or Edge (best WebRTC/TTS support)

Check your environment

node --version    # Should show v20.x or v22.x
npm --version     # Should show 10.x+

Don't have Node.js? Download from nodejs.org — pick the LTS version.

---

2. Installation (Step by Step)

Step 1: Clone the repository

git clone https://huggingface.co/muthuk1/OpenMAIC-React
cd OpenMAIC-React

Step 2: Install dependencies

npm install --legacy-peer-deps

Why --legacy-peer-deps? Some packages have peer dependency version mismatches. This flag tells npm to install them anyway. It's safe.

Step 3: Build workspace packages

The app uses two local packages that need to be built first:

# Build mathml2omml (MathML → OMML converter for PowerPoint export)
cd packages/mathml2omml
npm install
npm run build
cd ../..

# Build pptxgenjs (PowerPoint generation library)
cd packages/pptxgenjs
npm install @rollup/plugin-node-resolve @rollup/plugin-commonjs @rollup/plugin-typescript typescript tslib --save-dev
npx tsc --outDir ./dist-tsc --declaration --module es2020 --target es2016 --moduleResolution node --esModuleInterop true --allowSyntheticDefaultImports true --strict --strictNullChecks false --noImplicitAny false --lib dom,es2020 --skipLibCheck
mkdir -p dist
# Bundle compiled JS
cat > rollup.temp.mjs << 'EOF'
import resolve from "@rollup/plugin-node-resolve";
import commonjs from "@rollup/plugin-commonjs";
export default {
  input: "dist-tsc/pptxgen.js",
  output: [
    { file: "./dist/pptxgen.es.js", format: "es" },
    { file: "./dist/pptxgen.cjs.js", format: "cjs", exports: "default" },
  ],
  external: [/^node:.*/, "jszip"],
  plugins: [resolve({ preferBuiltins: true }), commonjs()]
};
EOF
npx rollup -c rollup.temp.mjs
cp types/index.d.ts dist/
rm rollup.temp.mjs
cd ../..

# Install local packages into the main project
npm install ./packages/mathml2omml ./packages/pptxgenjs --legacy-peer-deps

Step 4: Configure environment

cp .env.example .env

Edit .env with your API keys (see Section 4 for which keys you actually need).

Step 5: Verify the build

npm run build

You should see ✓ built in ~25s with no errors.

---

3. Running the App

Development mode (with hot reload)

npm run dev

Opens at http://localhost:5173

Production preview

npm run build
npm run preview

Opens at http://localhost:4173

What you'll see

1. Home page — A clean interface with a text area to type your lesson requirements
2. Upload a PDF or type what you want to teach
3. Click Generate — the app creates an AI classroom with slides, quizzes, and interactive content
4. Enter the classroom — watch the AI teacher present with voice, whiteboard, and discussion

---

4. Configuration — Which API Keys Do I Need?

The short answer: You only need ONE LLM API key to get started.

Everything else is optional. Here's what each key unlocks:

Feature	Required Key	Can You Skip It?
🧠 Classroom generation (slides, quizzes, actions)	Any LLM key (OpenAI, Google, etc.)	❌ No — this is the core feature
🗣️ Voice narration (TTS)	TTS provider key OR use browser TTS	✅ Yes — browser TTS works free
🎤 Voice input (ASR)	ASR provider key OR use browser ASR	✅ Yes — browser ASR works free
🖼️ AI image generation in slides	Image provider key	✅ Yes — slides work without images
🎬 AI video generation in slides	Video provider key	✅ Yes — slides work without videos
🔍 Web search for content enrichment	Tavily API key	✅ Yes — generation works without search
📄 Advanced PDF parsing	MinerU Cloud key	✅ Yes — built-in unpdf parser is free

Minimum viable setup: just ONE key

Pick one LLM provider and set its key in .env:

# Option A: Google Gemini (BEST FREE OPTION)
GOOGLE_API_KEY=your-key-here

# Option B: OpenAI
OPENAI_API_KEY=your-key-here

# Option C: DeepSeek (cheapest paid)
DEEPSEEK_API_KEY=your-key-here

---

5. Best & Most Cost-Effective AI Models

🧠 LLM — For Classroom Generation (THE most important choice)

Tier	Provider	Model	Price (per 1M tokens)	Quality	Best For
🆓 FREE	Google	gemini-2.5-flash	$0 (free tier: 500 req/day)	⭐⭐⭐⭐	Best free option. Start here.
🆓 FREE	Google	gemini-2.5-flash-lite	$0 (free tier)	⭐⭐⭐	Faster, simpler content
💰 Budget	DeepSeek	deepseek-chat	$0.14 input / $0.28 output	⭐⭐⭐⭐	Best bang-for-buck paid option
💰 Budget	GLM (ZhipuAI)	glm-4.7-flash	Free tier available	⭐⭐⭐⭐	Great for Chinese content
💵 Mid	OpenAI	gpt-4o-mini	$0.15 / $0.60	⭐⭐⭐⭐	Good balance of cost & quality
💵 Mid	Anthropic	claude-haiku-4-5	$0.80 / $4.00	⭐⭐⭐⭐⭐	Better slide layouts
💎 Premium	OpenAI	gpt-5.5	$2.00 / $10.00	⭐⭐⭐⭐⭐	Best overall quality
💎 Premium	Anthropic	claude-sonnet-4-5	$3.00 / $15.00	⭐⭐⭐⭐⭐	Best reasoning & creativity
💎 Premium	Google	gemini-2.5-pro	$1.25 / $10.00	⭐⭐⭐⭐⭐	Longest context (1M tokens)
🏠 Local	Ollama	llama3.3, qwen2.5	$0 (runs on your GPU)	⭐⭐⭐	Privacy, no internet needed

💡 My recommendation: Start with Google Gemini 2.5 Flash (free). If you need better quality, switch to DeepSeek ($0.14/M) or GPT-4o-mini ($0.15/M).

🗣️ TTS — Voice Narration

Tier	Provider	Voice	Price	Quality	Setup
🆓 FREE	Browser Native	System voices	$0	⭐⭐	No setup needed — works in Chrome/Edge
💰 Budget	OpenAI	alloy, nova, shimmer	$15.00/1M chars	⭐⭐⭐⭐⭐	Best quality-to-price ratio
💰 Budget	MiniMax	speech-02	~$0.50/1M chars (Chinese pricing)	⭐⭐⭐⭐	Great for Chinese voices
💵 Mid	Azure	500+ voices	$16.00/1M chars	⭐⭐⭐⭐⭐	Most voice variety, many languages
💵 Mid	ElevenLabs	Custom voices	$11.00/1M chars	⭐⭐⭐⭐⭐	Most natural sounding
💎 Advanced	VoxCPM	Voice cloning	Self-hosted	⭐⭐⭐⭐	Clone any voice

💡 My recommendation: Start with Browser TTS (free, decent quality in Chrome). Upgrade to OpenAI TTS ($15/1M chars) when you want natural voices.

🎤 ASR — Voice Input (Speech-to-Text)

Tier	Provider	Price	Quality
🆓 FREE	Browser Native (Web Speech API)	$0	⭐⭐⭐ — Works in Chrome/Edge
💰 Best	OpenAI Whisper	$0.006/minute	⭐⭐⭐⭐⭐ — Best accuracy
💰 Budget	Qwen ASR	Low (Chinese pricing)	⭐⭐⭐⭐ — Great for Chinese

💡 My recommendation: Browser ASR is free and good enough. Use Whisper only if you need high accuracy.

🖼️ Image Generation (Optional)

Tier	Provider	Model	Price per image	Quality
💰 Budget	OpenAI	gpt-image-1-mini	~$0.02	⭐⭐⭐⭐
💵 Mid	OpenAI	gpt-image-2	~$0.04-0.08	⭐⭐⭐⭐⭐
💵 Mid	Grok	grok-image	~$0.05	⭐⭐⭐⭐
💵 Mid	MiniMax	image-01	~$0.03	⭐⭐⭐⭐
💎 Premium	Seedream	seedream-5.0	~$0.02	⭐⭐⭐⭐⭐ (Chinese provider)

💡 My recommendation: Skip images initially. When ready, OpenAI gpt-image-1-mini at $0.02/image is excellent value.

🎬 Video Generation (Optional, Expensive)

Provider	Model	Price	Duration
Kling	kling-v2.6	~$0.10-0.30/video	5-10s
Seedance	seedance-1.5-pro	~$0.05-0.15/video	5-10s
Veo	veo-3	~$0.10/video	5-8s

💡 My recommendation: Skip video generation unless you specifically need it. It's expensive and slow (30-120s per video).

🔍 Web Search (Optional)

Provider	Free Tier	Paid Price
Tavily	1,000 free searches/month	$0.001/search after

💡 My recommendation: Get a free Tavily key — 1,000 searches/month is plenty.

📄 PDF Parsing

Provider	Price	Quality
unpdf (built-in)	$0 — always free	⭐⭐⭐ — Good for simple PDFs
MinerU (local)	$0 — self-hosted	⭐⭐⭐⭐ — Better for complex layouts
MinerU Cloud	Pay-per-use	⭐⭐⭐⭐⭐ — Best for scanned/complex PDFs

💡 My recommendation: The built-in unpdf parser is free and works fine for most PDFs. No setup needed.

---

6. Feature-by-Feature Setup

🧠 Core: Classroom Generation

This is the only required feature. You need ONE LLM key.

Option A: Google Gemini (FREE)

1. Go to aistudio.google.com
2. Click "Get API key" → "Create API key"
3. Add to .env:

   GOOGLE_API_KEY=AIzaSy...your-key
   

4. In the app: Settings → Providers → Google → select gemini-2.5-flash

Option B: OpenAI (Paid, best quality)

1. Go to platform.openai.com/api-keys
2. Create a new API key
3. Add credit ($5 minimum)
4. Add to .env:

   OPENAI_API_KEY=sk-...your-key
   

Option C: DeepSeek (Cheapest paid)

1. Go to platform.deepseek.com
2. Create account → Get API key
3. Add to .env:

   DEEPSEEK_API_KEY=sk-...your-key
   

Option D: Ollama (Free, local, needs GPU)

1. Install Ollama: ollama.ai
2. Pull a model: ollama pull llama3.3
3. Add to .env:

   OLLAMA_BASE_URL=http://localhost:11434/v1
   OLLAMA_MODELS=llama3.3
   ALLOW_LOCAL_NETWORKS=true
   

🗣️ Voice Narration (TTS)

Free option: Browser TTS (no setup needed)

• Works out of the box in Chrome, Edge, Safari
• In the app: Settings → Audio → TTS Provider → "Browser"

Paid option: OpenAI TTS

• Same API key as LLM (if you're using OpenAI)
• In the app: Settings → Audio → TTS Provider → "OpenAI" → Voice → "nova" (recommended)

🎤 Voice Input (ASR)

Free option: Browser ASR (no setup needed)

• Works in Chrome and Edge (not Firefox/Safari)
• Click the microphone button in the chat area

🔍 Web Search

1. Go to tavily.com → Sign up (free)
2. Get API key from dashboard
3. Add to .env:

   TAVILY_API_KEY=tvly-...your-key
   

4. Toggle "Web Search" on the home page when generating

🖼️ Image Generation

OpenAI Images (easiest):

• Same API key as LLM
• In the app: Settings → Image → Provider → "OpenAI Image" → Model → "GPT Image 1 Mini"
• Toggle "Enable Image Generation" on the home page

🎬 Video Generation

• Configure in Settings → Video → choose provider
• Video generation is slow (30-120 seconds per video) and expensive
• Only recommended for demo/showcase purposes

---

7. Free Tier & Zero-Cost Options

Completely free setup (no credit card needed):

# .env for 100% free setup
GOOGLE_API_KEY=your-gemini-key    # Free: 500 requests/day
TAVILY_API_KEY=your-tavily-key    # Free: 1,000 searches/month

What you get for free:

• ✅ Full classroom generation (slides, quizzes, interactive content)
• ✅ Multi-agent discussions
• ✅ Voice narration (browser TTS)
• ✅ Voice input (browser ASR)
• ✅ PDF parsing (built-in unpdf)
• ✅ Web search enrichment (1,000/month)
• ✅ Whiteboard
• ✅ PowerPoint export
• ✅ Classroom ZIP export/import
• ❌ AI image generation (needs paid key)
• ❌ AI video generation (needs paid key)
• ❌ Premium voice quality (needs paid TTS key)

Monthly cost estimates:

Usage Level	LLM	TTS	Images	Total
Hobby (5 classrooms/week)	$0 (Gemini free)	$0 (browser)	$0 (skip)	$0/month
Regular (3 classrooms/day)	~$2 (DeepSeek)	$0 (browser)	$0 (skip)	~$2/month
Power user (10/day, with images)	~$5 (DeepSeek)	~$3 (OpenAI TTS)	~$5 (images)	~$13/month
Premium (full features)	~$20 (GPT-5.5)	~$10 (Azure TTS)	~$15 (images+video)	~$45/month

---

8. Recommended Starter Configurations

🟢 Configuration A: "Zero Cost Beginner"

GOOGLE_API_KEY=your-key

• LLM: Gemini 2.5 Flash (free)
• TTS: Browser native (free)
• ASR: Browser native (free)
• PDF: unpdf built-in (free)
• Images/Video: disabled
• Cost: $0/month

🟡 Configuration B: "Best Value"

GOOGLE_API_KEY=your-key
DEEPSEEK_API_KEY=your-key
TAVILY_API_KEY=your-key

• LLM: DeepSeek Chat for generation, Gemini for backup
• TTS: Browser native
• Web Search: Tavily (1,000 free/month)
• Cost: ~$2-5/month

🔵 Configuration C: "Full Experience"

OPENAI_API_KEY=your-key
GOOGLE_API_KEY=your-key
TAVILY_API_KEY=your-key

• LLM: GPT-4o-mini (primary), Gemini 2.5 Pro (long docs)
• TTS: OpenAI TTS (same key)
• ASR: OpenAI Whisper (same key)
• Images: OpenAI Image (same key)
• Web Search: Tavily
• Cost: ~$10-20/month

🟣 Configuration D: "Chinese Content Focus"

GLM_API_KEY=your-key
QWEN_API_KEY=your-key
DEEPSEEK_API_KEY=your-key

• LLM: GLM-4.7-Flash or DeepSeek
• TTS: GLM TTS or MiniMax
• Best for Chinese language classroom content
• Cost: ~$2-5/month

---

9. Docker Deployment

Using Docker Compose (recommended for production)

# 1. Create .env file with your API keys
cp .env.example .env
# Edit .env with your keys

# 2. Build and run
docker compose up -d

# 3. Access the app
open http://localhost:3000

Using Dockerfile directly

docker build -t multimind-classroom .
docker run -p 3000:3000 --env-file .env multimind-classroom

Access Control (optional)

To password-protect your deployment:

ACCESS_CODE=my-secret-password

Users will see a login screen and must enter this code.

---

10. Troubleshooting

Build fails with "Cannot find module"

# Clean install
rm -rf node_modules package-lock.json
npm install --legacy-peer-deps
npm install ./packages/mathml2omml ./packages/pptxgenjs --legacy-peer-deps
npm run build

"API key required" error

• Make sure your .env file is in the project root (same directory as package.json)
• Make sure you selected the correct provider in Settings → Providers
• Restart the dev server after changing .env

Browser TTS not working

• Browser TTS only works in Chrome, Edge, and Safari
• Firefox does not support Web Speech API synthesis
• Make sure your browser is not muted
• Try a different voice in Settings → Audio → TTS

Classroom generation is slow

• Gemini 2.5 Flash is fastest (2-5 seconds per scene)
• GPT-4o-mini is fast (3-8 seconds per scene)
• Claude models are slower (5-15 seconds per scene)
• A 10-slide classroom typically takes 30-120 seconds total

"Failed to parse PDF"

• The built-in unpdf parser works for most text-based PDFs
• Scanned/image PDFs need MinerU Cloud
• Very large PDFs (>50MB) may need to be split
• Try copy-pasting the text content directly into the requirements field

Images not loading in slides

• Check that you've enabled image generation in Settings
• Check that the image provider has a valid API key
• Generated images are stored in IndexedDB — clearing browser data removes them

Whiteboard not showing

• Click the pencil (✏️) icon in the bottom toolbar
• Whiteboard only appears on slide-type scenes (not quiz or interactive)

---

11. FAQ

Q: Do I need to pay for anything? A: No. You can run the entire app for free using Google Gemini's free tier + browser TTS/ASR.

Q: Can I use my own local LLM? A: Yes! Install Ollama, pull a model (e.g., ollama pull llama3.3), and configure it in .env. You need a GPU with at least 8GB VRAM for good results.

Q: How much does it cost to generate one classroom? A: With Gemini free tier: $0. With DeepSeek: ~$0.01-0.05. With GPT-5.5: ~$0.20-0.50. Depends on PDF length and number of slides.

Q: Can I export to PowerPoint? A: Yes! Click the export button (⬇️) in the classroom header and select "Export PPTX". All slides, text, shapes, charts, and images are included.

Q: Does it work offline? A: The app itself runs locally, but AI generation needs internet access to call LLM APIs. If you use Ollama (local LLM), you can generate content offline. Previously generated classrooms are stored in IndexedDB and accessible offline.

Q: What languages are supported? A: The UI supports 5 languages (Chinese, English, Japanese, Russian, Arabic). Classroom content can be generated in ANY language — just specify your desired language in the requirements field or let the AI auto-detect from your PDF.

Q: Can multiple students use the same classroom? A: Currently, classrooms are stored locally in your browser. To share, export as a .multimind.zip file and share that file. Others can import it.

Q: What PDF format works best? A: Text-based PDFs work best. The parser extracts text and images. For scanned PDFs, use MinerU Cloud. Maximum recommended size: 50MB.

Q: How do I switch between AI providers mid-use? A: Click the Settings gear (⚙️) → Providers tab → select a different provider and model. The change takes effect immediately for the next generation.

---

Quick Start Cheat Sheet

# 1. Clone
git clone https://huggingface.co/muthuk1/OpenMAIC-React && cd OpenMAIC-React

# 2. Install
npm install --legacy-peer-deps

# 3. Build workspace packages
cd packages/mathml2omml && npm install && npm run build && cd ../..

# 4. Configure (minimum: one LLM key)
cp .env.example .env
echo "GOOGLE_API_KEY=your-key-here" >> .env

# 5. Run
npm run dev

# 6. Open http://localhost:5173 and generate your first classroom!

That's it! Type a topic, click Generate, and watch MultiMind Classroom create an interactive AI lesson. 🎓