🦁 SomoPal — KCSE AI Tutor

Voice-first Progressive Web App for Kenyan secondary students preparing for KCSE "Somo" = Lesson, "Pal" = Partner

---

🎯 What is SomoPal?

SomoPal is an AI-powered study companion designed specifically for Form 4 Kenyan students like Ivy — who learns best by speaking, not typing. She clicks a link, speaks to it, and gets KCSE-ready help.

Key Features

Feature	Description
🎤 Voice-First	Everything works via voice — speak, listen, learn
📱 Zero Setup	Click a link and start — no app store install needed
🔌 Offline Mode	Falls back to built-in KCSE knowledge base when no internet
🤖 AI Powered	NVIDIA NIM API (online) + WebLLM/Qwen 2.5 3B (offline, WebGPU)
📸 Image Upload	Snap a photo of notes or past papers — AI breaks it down step by step
📊 Parent Dashboard	Separate link for parents to monitor progress
🇰🇷 KCSE-Aware	Knows KNEC structure, mark schemes, and all Form 4 subjects
🌍 Kiswahili Support	Speaks back in English or Kiswahili based on preference
📅 Smart Timetable	Auto-generates personal study schedule
📝 Dual Output	Shows text (for notes) + reads aloud automatically

---

📁 Project Structure

somopal/
├── index.html          ← Main app (onboarding + chat interface)
├── manifest.json       ← PWA manifest
├── sw.js               ← Service Worker (offline caching)
├── icons/
│   ├── icon-192.png    ← App icon
│   └── icon-512.png    ← App icon (large)
├── styles/
│   └── main.css        ← Dark theme, mobile-optimized styles
├── src/
│   ├── api.js          ← NVIDIA NIM + WebLLM integration
│   ├── onboarding.js   ← Voice-based interview flow
│   ├── router.js       ← Smart subject classifier
│   ├── knowledge-base.js ← KCSE syllabus + set books + topics
│   ├── predictor.js    ← KCSE topic prediction engine
│   ├── storage.js      ← LocalStorage + IndexedDB layer
│   └── dashboard.js    ← Parent progress dashboard
└── README.md           ← This file

---

🚀 Quick Start

Option 1: Local (Development)

cd side-projects/somopal/
# Any HTTP server works:
python3 -m http.server 8080
# Then open: http://localhost:8080

Option 2: Deploy (Production)

GitHub Pages (Free)

# Push to a GitHub repository
gh repo create somopal-app --public
cd side-projects/somopal/
git init
git add .
git commit -m "Initial SomoPal commit"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/somopal-app.git
git push -u origin main
# Enable GitHub Pages in repository settings

Vercel / Netlify (Free, automatic HTTPS)

# Drag and drop the somopal/ folder to netlify.com/drop
# Or use Vercel CLI:
npx vercel

Self-Hosted (Kenya Server)

# Use Nginx on a Kenya-based VPS
# sudo apt install nginx
# sudo cp -r somopal/* /var/www/html/
# sudo systemctl restart nginx
# Share the link: https://your-domain.ke

Option 3: Share via Link (easiest)

Share the URL directly with Ivy. She opens it → clicks Allow on microphone → and starts talking.

Optional: Share as WhatsApp Webhook

Host it on HTTPS and share the link via WhatsApp. She adds it to Samsung's home screen via "Add to Home Screen" in Chrome.

---

🔧 Configuration

NVIDIA NIM API Key

1. Go to build.nvidia.com/explore/discover
2. Sign up for a free account
3. Get your API key
4. In SomoPal, tap ⚙️ (Settings) and paste the key

Free tier available — enough for hundreds of questions per month.

Offline Mode

Works automatically when no internet is detected. Uses:

• WebLLM with Qwen 2.5 3B model (requires WebGPU — Chrome 113+ on Android)
• Built-in Knowledge Base (syllabus, topics, grade boundaries) as final fallback

Parent Dashboard

Access via: index.html?dashboard=1 Share this link with parents/guardians for progress monitoring.

---

📋 KCSE Subjects Covered

Subject	KNEC Code	Papers
Mathematics	121/1, 121/2	Paper 1 & 2
English	101/1, 101/2, 101/3	Paper 1, 2 & 3
Kiswahili	103/1, 103/2	Paper 1 & 2
Physics	232/1, 232/2, 232/3	Paper 1, 2 & 3
Chemistry	233/1, 233/2, 233/3	Paper 1, 2 & 3
Biology	231/1, 231/2, 231/3	Paper 1, 2 & 3
History	311/1, 311/2, 311/3	Paper 1, 2 & 3
Geography	312/1, 312/2	Paper 1 & 2
Business	105/1, 105/2	Paper 1 & 2
Agriculture	443/1, 443/2	Paper 1 & 2

---

🧪 Testing on Samsung Android

1. Open Chrome on Samsung device
2. Navigate to the hosted URL
3. Allow microphone access when prompted
4. Tap "Add to Home Screen" → "Install" (PWA)
5. Launch from home screen (no browser chrome)
6. Tap 🎤 and start speaking!

Browser Compatibility

Browser	Voice STT	TTS	PWA	Offline
Samsung Chrome	✅	✅	✅	✅
Samsung Internet	✅	✅	✅	✅
Samsung Edge	✅	✅	⚠️	✅
Firefox Android	✅	✅	❌	✅

Note: Firefox doesn't support PWA installation on Android. Works fine in-browser though.

---

🏗️ Architecture

┌──────────────────────────────────────┐
│            🦁 SomoPal                │
├──────────────────────────────────────┤
│  index.html (App Shell)               │
│  ├── Onboarding (voice interview)     │
│  ├── Chat Interface                   │
│  └── Parent Dashboard                 │
├──────────────────────────────────────┤
│  src/router.js       ← Subject classifier  │
│  src/knowledge-base.js ← KCSE syllabus    │
│  src/predictor.js     ← Topic predictor    │
│  src/onboarding.js    ← Voice interview   │
│  src/api.js           ← NVIDIA + WebLLM   │
│  src/storage.js       ← IndexedDB + LS    │
│  src/dashboard.js     ← Parent dashboard  │
├──────────────────────────────────────┤
│  sw.js (Service Worker)               │
│  └── Cache-first, network-fallback    │
│                                       │
│  manifest.json (PWA)                  │
│  └── Add to Home Screen              │
└──────────────────────────────────────┘

---

📊 How the Onboarding Works

1. "What's your name?" → Records name
2. "Which class?" → Form 1-4
3. "Which subjects?" → Multi-select or voice input
4. "What grade are you aiming for?" → Target grade
5. "What's your current grade?" → Baseline
6. "What are your weak areas?" → Personalization
7. "When can you study?" → Schedule generation
8. "English, Kiswahili, or mix?" → Language preference
9. Profile summary → Confirmation → Start studying!

---

📈 Progress Tracking

SomoPal tracks:

• ✅ Total study time
• ✅ Daily streak
• ✅ Best streak
• ✅ Subject-level progress
• ✅ Conversations per subject
• ✅ Roadmap from current grade to target

---

🔒 Privacy & Data

• All data stored locally on the device (IndexedDB + LocalStorage)
• No tracking, no analytics, no third-party cookies
• NVIDIA API calls only made when internet is available and API key is set
• Parent dashboard accesses only local data on the same device
• Export data feature available in Settings

---

📝 Roadmap (Future Phases)

• Phase 2: Multi-user profiles (siblings sharing phone), past paper database with auto-grading
• Phase 3: Teacher portal assignment creation and student monitoring, peer tutor matching
• Phase 4: SMS integration for feature phones (no smartphone), WhatsApp bot integration

---

🦁 CoHusdex

Where Economic Intelligence Meets Autonomous Multi-Agent Execution

Built by Valentine Owuor in Kakamega, Kenya.

"Every Form 4 student deserves a personal tutor. SomoPal makes it accessible to all."

---

License

© 2024 CoHusdex. All rights reserved.