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](#1-prerequisites)
2. [Installation (Step by Step)](#2-installation-step-by-step)
3. [Running the App](#3-running-the-app)
4. [Configuration — Which API Keys Do I Need?](#4-configuration--which-api-keys-do-i-need)
5. [Best & Most Cost-Effective AI Models](#5-best--most-cost-effective-ai-models)
6. [Feature-by-Feature Setup](#6-feature-by-feature-setup)
7. [Free Tier & Zero-Cost Options](#7-free-tier--zero-cost-options)
8. [Recommended Starter Configurations](#8-recommended-starter-configurations)
9. [Docker Deployment](#9-docker-deployment)
10. [Troubleshooting](#10-troubleshooting)
11. [FAQ](#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

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

**Don't have Node.js?** Download from [nodejs.org](https://nodejs.org/) — pick the **LTS** version.

---

## 2. Installation (Step by Step)

### Step 1: Clone the repository

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

### Step 2: Install dependencies

```bash
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:

```bash
# 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

```bash
cp .env.example .env
```

Edit `.env` with your API keys (see [Section 4](#4-configuration--which-api-keys-do-i-need) for which keys you actually need).

### Step 5: Verify the build

```bash
npm run build
```

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

---

## 3. Running the App

### Development mode (with hot reload)

```bash
npm run dev
```

Opens at **http://localhost:5173**

### Production preview

```bash
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`:

```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](https://aistudio.google.com/)
2. Click "Get API key" → "Create API key"
3. Add to `.env`:
   ```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](https://platform.openai.com/api-keys)
2. Create a new API key
3. Add credit ($5 minimum)
4. Add to `.env`:
   ```env
   OPENAI_API_KEY=sk-...your-key
   ```

**Option C: DeepSeek (Cheapest paid)**

1. Go to [platform.deepseek.com](https://platform.deepseek.com/)
2. Create account → Get API key
3. Add to `.env`:
   ```env
   DEEPSEEK_API_KEY=sk-...your-key
   ```

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

1. Install Ollama: [ollama.ai](https://ollama.ai/)
2. Pull a model: `ollama pull llama3.3`
3. Add to `.env`:
   ```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](https://tavily.com/) → Sign up (free)
2. Get API key from dashboard
3. Add to `.env`:
   ```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
# .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"

```env
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"

```env
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"

```env
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"

```env
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)

```bash
# 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

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

### Access Control (optional)

To password-protect your deployment:

```env
ACCESS_CODE=my-secret-password
```

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

---

## 10. Troubleshooting

### Build fails with "Cannot find module"

```bash
# 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

```bash
# 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. 🎓